Rebus API

This topic covers how you set up Rebus so that you can retrieve widget data from the Rebus database through the Rebus Application Programming Interface (API).

How the API works

Each request to the Rebus database must come from an authenticated client (e.g., an application on your end that sends API requests.). The authentication details that a client needs to be authenticated are stored on the Rebus side in an API user account set up on the Organization Admin screen. An API user account is authorized to send API requests to the data collections of a set of specified widgets.

Events of a typical Rebus API transaction:

1. Client (i.e., your application) sends POST query with authentication credentials.

2. Rebus API server authenticates the client. If the client has correct credentials and its IP is whitelisted, the client will be authenticated and the Rebus API server will send to the client a session cookie, which lets the client send queries for a limited time.

3. Client sends GET query to get data from a widget that’s assigned to its API user account.

4. Rebus API server responds with requested data in JavaScript Object Notation (JSON) format.

Creating API User accounts

A tab on the Organization Admin screen, API Users, lets you set up API user accounts through which you can send GET queries to retrieve widget data from the Rebus database.

Pre-requisites

• Access to the Organization Admin screen.

• The IP address of the machine that will be sending requests. In most cases, this should be the static IP address of your external (public) network. The website https://www.whatismyip.com/ is a good online tool that can help you find the right IP address.

1. Go to the Organization Admin screen and click the API Users tab.

2. Click the ‘New User’ button and fill in the needed details. An API user account stores the following authentication-related details:

Fields to set up API user accounts

Field	What You Enter…
User ID	Set up automatically. Identifier of account that is sending API requests.
Password	Password for account. Password must meet the following criteria: 1) Minimum length of 12 characters. 2) Contain at least one of each of the following: uppercase and lowercase letters, numbers, and special characters.
White Listed IP	The authorized IP address from where the API requests are sent. In most cases, this should be the static IP address of your external (public) network. The website https://www.whatismyip.com/ is a good online tool that can help you find the right IP address.

For an application to be authenticated to send API requests, it needs to be configured with the user ID and password of an API user account and its IP address needs to be among the IP addresses whitelisted for that account. You can create up to five API user accounts.

3. Click ‘Save API User’. The API user account is created.

Assigning Widgets and Setting the GET Query Endpoint URL

Pre-requisites

• Widgets set up that have the data you want to retrieve via API.

After setting up the API user account on the Organization Admin screen, do the following:

1. Open the API user account’s Assigned Widgets tab.

2. Assign to the user account the widget data collections from which this account is authorized to retrieve data. You can move widgets from the Available list to the Assigned list by clicking the ‘<’ button.

To set the endpoint URL of the GET query for an assigned widget, do the following:

1. Click the widget’s name and then click the gearwheel button. The widget’s URL Builder form appears. This form shows all the widget’s parameters and the default values that are used to populate the widget. At the bottom, the URL value shows the query string of the widget’s GET query endpoint URL.

2. Adjust the parameter values to those you want the GET query to use when you are retrieving this widget’s data via API. The query string is changed to reflect any changes made to the parameter values.

3. Copy the query string at the bottom of the form and paste it someplace where you can easily get it when you are configuring the application that will be sending GET queries. You will append the query string to another value to build the full GET query endpoint URL for this widget.

Example of query string:

5b8721984eca9d67e53c80c9?parameters=%7B%22PICK_REFERENCE%22:%22ABC%22,%22PICK_TYPE%22:%22E,M,T,G%22,%22PICK_STATUS%22:%22CANCELLED%22%7D

Sending GET Queries for a Widget

Authenticating to Rebus API server

The Rebus API system uses a stateless approach to retrieve data from widgets. Stateless protocol does not require the server to retain server information or session details. Your authentication credentials will be included in the request header of each request.

1. In Postman, in the request Authorization tab, select Basic Auth from the Type dropdown list.

2. Enter your API username and password in the Username and Password fields. In the request Headers, the Authorization header will pass the API a Base64 encoded string representing your username and password values.

GET Queries

The client can now send GET queries to the Rebus API server. A properly formatted GET query endpoint URL comprises two parts.

• Part 1: The host and path name, which is constant:

  https://api.rebusap.com/inbound/extract/
  

Note

The host and path name URL for your company might differ from the URL shown in the example above. To find out the correct URL for your company’s data, please contact Rebus Customer Support.

and

• Part 2: The query string for the widget, which is taken from the API user account record on the Organization Admin screen.

Example:

5b8721984eca9d67e53c80c9?parameters=%7B%22PICK_REFERENCE%22:%22ABC%22,%22PICK_TYPE%22:%22E,M,T,G%22,%22PICK_STATUS%22:%22CANCELLED%22%7D

To build the GET query endpoint URL, the query string is appended to the host and path name:

Example:

https://api.rebusap.com/inbound/extract/5b8721984eca9d67e53c80c9?parameters=%7B%22PICK_REFERENCE%22:%22ABC%22,%22PICK_TYPE%22:%22E,M,T,G%22,%22PICK_STATUS%22:%22CANCELLED%22%7D

Example in Postman:

Setting up Authentication to 3rd Party APIs

You can set up the credentials that Rebus uses to authenticate to the application programming interfaces (APIs) of third-party systems when it’s doing mass product status updates through the Quality Assurance (QA) module. A tab on the System Details screen, Communication, stores a set of credentials and API endpoints. For each third-party system, you can create a set of credentials that lets Rebus authenticate through one of the following:

Authentication Option	Key Value pairs that are put in request header to authenticate API request
API Key	Key: “Header” Value: Header value from Communication tab. Key: ”API Key” Value: API Key value from Communication tab.
Basic	Key: “Authorization” Value: String of username and password (encoded using Base 64)

You also set up details for the API endpoints to which Rebus is authorized to send its API requests when mass updating product statuses on the third-party system. The credentials are included in the header of the API requests sent to those API endpoints.

Creating a Set of Credentials to send API requests to a Third-Party System

1. Go to Admin Tools > System > Organization Admin > System Details tab. The System Information screen opens.

2. From the Existing Systems list, select the third-party system for which you want to set up a set of credentials to authenticate API requests. The main interface is filled with a System Information tab that’s populated with the details of the selected system.

3. Next to the System Information tab, click the Communication tab and then click ‘New’. Two fields, Method and Authentication, appear.

4. In Method, leave value at default, ‘API’.

5. In the Authentication field, select how Rebus will populate the request header with authentication information: API Key or Basic Authentication.

Selected API Key	Selected Basic Authentication
In the API Key field, enter the string of the API key. In the Header field, enter the Header value that, combined with the API Key, will authenticate the message to the third -party system.	Enter Username and password combination that will authenticate Rebus to the third-party system

6. Create an API endpoint record for each API endpoint at the third-party system to which Rebus will be sending API requests: To create an API endpoint record, in the API Endpoints table:

   1. Click the ‘+’’ symbol.

   2. Fill out the Create API Endpoint form. Its fields are described in the table below:

   Field	Description
   Name	Name of API endpoint.
   URL	URL of API endpoint.
   Method	HTTP request type that’s used on the endpoint GET - to retrieve a resource. PUT - to update a resource. POST - to create a resource. DELETE - to remove a resource.
   Content Type	Data format of request: Application/JSON Text

   3. Click ‘Create’. You have created an API endpoint record.

You have created a communication record: A set of credentials to authenticate to a third-party system. The Quality Assurance (QA) module lets you mass update the status of your products across different systems, send notifications for updates, and consult the module’ss change history.