REST data source in Jitterbit App Builder

Introduction

The REST data source lets you connect App Builder to various REST servers (including other instances of App Builder), or for use with REST objects. A REST data source server's configuration is used across all REST endpoints.

Setting up a REST data source involves the following steps:

Create a REST data source server.
Configure request headers.
Configure request body.
Configure query string parameters.
Create REST endpoints for each API method being called.
Add REST endpoints.
(Optional) Override endpoint request/response content types.
(Optional) Configure response pagination.

Since App Builder 4.45, you can also create a REST endpoint from an OpenAPI document.

Create a REST data server

To create a REST data server, follow these steps:

Select IDE > Data Servers.
Click the + Server button.
In the Server Settings section, set the following fields:
- Server Name: Enter a name for the REST server.
- Type: Select REST API.
- URL: Enter the URL of the server to connect to.
  
  Note
  
  Endpoints are configured in the next section.
- Request Content Type and Response Content Type: Select the request and response content types. (Typically, REST servers communicate via JSON.)
(Optional) Expand the Security Settings section, then set the following:
- Security Provider: Select the required security provider.
- User Name: Enter the username for the security provider service.
- Password: Enter the password for the security provider service.
Tip

Most REST APIs use an API key in the header (configured in the next section).
(Optional) Description: Enter a description for this server.
Click the Save button, then close the dialog. You should see your new REST data server in the list.

Configure request headers

Most REST services require you to pass in an API key using the request header. To configure the request header, follow these steps:

Select IDE > Data Servers.
Click the Open record button for your new REST data server.
In the Server popup, under Server Settings, click the Endpoints icon.
In the Web Service Parameters panel, click the + Parameter button. A new row appears in the panel. Set the values as follows:
- Type: Select Header.
- Name: Enter the name of the header parameter. (For App Builder REST servers, the API key is passed using X-API-Key.)
- Value: Enter the value of the header parameter.
- Usage Type: (Optional) Select the usage type for this parameter.
Click the icon to save the parameter.

Configure request body

To change how the payload is structured when using POST or PUT methods, follow these steps:

In the Endpoints panel, select More > Edge Case. The Endpoint Edge Case dialog opens.
Click the Edit button.
In the Request section, set Request Body to one of the following values:
- Object: (Default) The payload is sent as a single JSON object. Use this when creating or updating a single record.
  Example
```
{
  "id": 123,
  "name": "A single record"
}
```
- Array: The payload is sent as a JSON array of objects. Use this for sending a batch of multiple records in one request.
  Example
```
[
  { "id": 123, "name": "First record" },
  { "id": 124, "name": "Second record" }
]
```
- Skip Root: For payloads that are wrapped in a top-level object, this option ignores the wrapper and sends the first child element as the payload. This is useful for 'drill down' scenarios.
  
  For example, if the system generates a payload with a data wrapper, Skip Root sends only the content inside data.
  Example Payload Sent
```
{
  "id": 123,
  "name": "The actual record"
}
```
Click the Save button, then close the dialog.

Configure query string parameters

If you have common query string parameters to use across end points you can configure them with the following steps:

Select IDE > Data Servers.
Click the Open record button for your new REST data server.
In the Server popup, under Server Settings, click the Endpoints icon.
In the Web Service Parameters panel, click the + Parameter button. A new row appears in the panel. Set values in the row as follows:
- Type: Select Query.
- Name: Enter the name of the query string parameter.
- Value: Enter the value of the query string parameter.
- Usage Type: (Optional) Select the usage type for this parameter.
Click the icon to save the parameter.

Add REST endpoints

Once your REST Data Server has been configured, you can add API endpoints.

To add an endpoint, follow these steps:

Select IDE > Data Servers.
Click the Open record button for your new REST data server.
In the Server popup, under Server Settings, click the Endpoints icon.
In the Endpoints panel, click the + Endpoint button. A new row appears in the panel. Set values in the row as follows:
- Name: Enter the name of the endpoint.
- Endpoint: Enter the endpoint. (This value is appended to the REST Data Server URL set in an earlier section.)
- Method: Select the HTTP method for the endpoint.
Click the icon to save the endpoint.

Override endpoint request/response content types

The default value for request and response content types is inherited from the server content type. The available content type values are as follows:

File
Form
JSON
Multipart
Plain Text
XML

To override the endpoint request or response content types, follow these steps:

In the Endpoints panel, select More > Edge Case. The Endpoint Edge Case dialog opens.
Click the Edit button.
In the Content Type section, set values for the following:
- Request: Select the overriding request content type.
- Response: Select the overriding response content type.
Click the Save button, then close the dialog.
To review the proposed query, click the Discover button. The Endpoint dialog opens.
In the Endpoint dialog, click the Discover button to execute the query. This action does the following:
- Generates input parameters for any sample input entered.
- Generates output tables for any data coming returned by the endpoint.
Close the Endpoint dialog.
In the Endpoints section, click the Test Connection button, then click the Proceed button to call the endpoint. If input parameters are defined, their test values are sent.

Configure response pagination

To configure response pagination, follow these steps:

Select IDE > Data Servers.
Click the Open record button for your new REST data server.
In the Server popup, under Server Settings, click the Endpoints icon.
In the Web Service Parameters panel, click the + Parameter button. A new row appears in the panel. Set values in the row as follows:
- Type: Select Query.
- Name: Enter the string expected by the service. (Examples include Limit, _limit.)
- Value: Enter the number of records per page.
- Usage Type: Open the menu, then select Request Limit.
Click the icon to save the parameter.
Click the + Parameter button. A new row appears in the panel. Choose one of the following pagination methods, then set the values accordingly as follows:
- Request Offset: Make the service skip a number of records. Set values in the row as follows:
  - Type: Query
  - Name: Request Offset
  - (Optional) Value: Enter the number of records to skip.
  - Usage Type: Open the menu, then select Request Offset.
- Request Page Number: Fetch a specific page number. Set values in the row as follows:
  - Type: Query
  - Name: Request Page Number
  - (Optional) Value: Enter the number of the page to fetch.
  - Usage Type: Open the menu, then select Request page number.
- Next Token: Fetch records from a specified point. Set values in the row as follows:
  - Type: Query
  - Name: Next Token
  - (Optional) Value: Enter the key for the record to start from.
  - Usage Type: Open the menu, then select Next Token.
Click the icon to save the parameter.