REST Direct Receiver

This topic describes how to set up a REST Direct Receiver for use with an inbound integration endpoint (IIEP).

Representational State Transfer (REST) is a software architecture style that you can use to design web services. As an architecture style, REST does not require processing and is naturally more flexible. Unlike SOAP (Simple Object Access Protocol), REST does not have to use XML to provide the response. You can find REST-based web services that output the data as Comma Separated Value (CSV), JavaScript Object Notation (JSON), and Really Simple Syndication (RSS). The REST Direct Receiver supported formats include XML files using STEPXML or Generic XML.

To learn more about REST, search for resources on the web.

For information about how to use the STEP REST API, access the Technical Documentation accessible at [system]/sdk or from the Resources section of the system's Start Page.

The REST Direct Receiver functions differently from the REST Receiver. Rather than using a hotfolder to stage the import, the REST Direct Receiver sends a REST call that immediately initiates a new import process.

Important: The REST call will fail and an error will be generated if the IIEP is disabled or not scheduled to occur, if there are too many Background Processes waiting in the queue, or when file names contain forbidden characters. Scheduling ensures that old background processes are regularly cleaned up so they do not fill up the queue.

Prerequisites

When an inbound integration endpoint (IIEP) has been configured to use the REST Receiver, files can be posted to the IIEP via HTTP POST to the following URL:

[Host]/restapiv2/inbound-integration-endpoints/[Endpoint ID]/upload-direct?context=[Existing Context]&workspace=Main

The request header 'Content-Type' must have the value 'application/octet-stream' and basic authorization must be used. For example, the 'Authorization' header must have the value 'Basic ' combined with a 64-bit encoding of [Username]:[Password]. For example, 'Basic c3RlcHN5czpzdGVwc3lz.'

In the URL shown above, the context and workspace qualifiers have no significance, but they are required for the REST API.

Alternatively, on Stibo Systems SaaS environments, authentication can also be implemented using an OAuth Client Credentials flow. To implement this type of authentication, client credentials must be created in the SaaS Authentication broker and mapped to an existing STEP user account, as follows:

  1. On the STEP side, create a service account user in the appropriate user group with the ID 'service-account-[client ID]' (e.g.: service-account-my-m2m-integration).

  2. For the new service account user, assign a random and strong password.

  3. Create a Stibo Systems Service Portal request and provide the service account user ID, the STEP system in question, and an email recipient for the OIDC details to have the client credentials created for this user account.

  4. Test that using the client_credentials grant type, the client application can obtain tokens from the OIDC token endpoint that is specified in the response to the following URL:

    [Host]/auth/.well-known/openid-configuration

Important: When using the REST Direct Receiver, the Transactional Setting of the IIEP will be force-set to 'None'.

Configuration

After completing the prerequisite steps, edit the receiver of the IIEP.

  1. For Receiver, choose REST Direct.

  2. Click the Next button to continue with the IIEP - Configure Endpoint and subsequent steps.