Consume external REST APIs in Jitterbit App Builder

Introduction

This guide gives an overview of how to connect to and consume external REST APIs as data sources within App Builder. A REST data source server's configuration is used across all REST endpoints.

Setting up and using a REST data source involves these main stages:

1. Create a REST data source server: Establish the initial connection to the base URL of the REST API.

2. Configure and add endpoints: Define the specific API endpoints you want to access, including their parameters, headers, and methods.

3. Use REST Objects for full integration: Abstract the configured API into a REST Object for seamless CRUD operations and UI integration.

Throughout this guide, the free Alpha Vantage stock data API is used as a practical example.

Create a REST data source server

To create a REST data server, follow these steps:

1. Select IDE > Data Servers.

2. Click the + Server button.

3. In the Server Settings section, set the following fields:

   • Server Name: Enter a descriptive name for the server. For our example, use Alpha Vantage.

   • Type: Select REST API.

   • URL: Enter the base URL provided in your API's documentation. For Alpha Vantage, this is https://www.alphavantage.co/.

     Note

     Specific endpoints are configured in a later step.

   • Request Content Type and Response Content Type: Select the request and response content types. Typically, this is JSON.

4. (Optional) Expand the Security Settings section if your API requires username/password authentication at the server level.

   Tip

   Most REST APIs, including Alpha Vantage, use an API key in the header or query string. This is configured in the next section.

5. (Optional) Description: Enter a description for this server.

6. Click the Save button, then close the dialog. You should see your new REST data server in the list.

Configure and add REST endpoints

After creating the data source server, you must configure its parameters and define the API endpoints you want to access.

Configure common parameters (headers and query strings)

You can define parameters that apply to all endpoints on the server, such as for authentication. Most REST services require you to pass in an API key.

To configure a common parameter, follow these steps:

1. In the Data Servers list, click the Open record button for your new REST data server.

2. In the Server popup, under Server Settings, click the Endpoints icon.

3. In the Web Service Parameters panel, click the + Parameter button. A new row appears.

4. Set the values based on your API's requirements. For our Alpha Vantage example, we need to add the API key as a query string parameter:

   • Type: Select Query.

   • Name: Enter the name of the parameter. For this example, use apikey. The name must match what the API expects.

   • Value: Paste your unique API key.

   • Usage Type: (Optional) Select a usage type.

5. Click the icon to save the parameter.

Add a REST endpoint

Once your REST data server has been configured, you can add specific API endpoints.

To add an endpoint, follow these steps:

1. In the Endpoints panel, click the + Endpoint button. A new row appears.

2. Set the values in the row as follows. For our example, we will create an endpoint to get a global stock quote:

   • Name: Give the endpoint a descriptive name. For this example, use global_quote. This name is used to identify the resulting data table in App Builder.

   • Endpoint: Enter the part of the URL that specifies the resource. For this example, a global quote is obtained by entering the following, which includes a placeholder {{ticker}} for a parameter defined next:

     query?function=GLOBAL_QUOTE&symbol={{ticker}}
     

   • Method: Select the HTTP method. For this example, select GET.

3. Click the icon to save the endpoint.

Define endpoint-specific parameters

Now add a parameter for the stock ticker to query:

1. In the Web Service Parameters panel, click + Parameter again.

2. Set the values as follows:

   • Type: Select Query.

   • Name: Enter a name for this parameter. For this example, ticker.

   • Value: Leave blank, as we want to provide this dynamically.

   • Usage Type: Select Input.

   • Test Value: Enter AAPL (for Apple Corp.) for testing purposes.

3. Click the icon to save the parameter.

Test the connection

Finally, test the endpoint to ensure your configuration is correct.

1. In the Endpoints panel, select the newly created global_quote endpoint.

2. Click Test Connection, then Proceed.

If the configuration is correct, a "Connection test passed" message appears, and the data returned from the API (the information for AAPL) is displayed in the Text Results section.

Your API endpoint is now connected. App Builder automatically creates a data table named global_quote (from the endpoint name) in the Alpha Vantage data source, which you can now use to build UI components.

Alternative: Import from an OpenAPI document

If you have an OpenAPI (Swagger) document for your REST API, you can import it to automatically generate endpoints. See Import an OpenAPI document for detailed instructions.

Use REST Objects for full integration

REST Objects allow App Builder developers to make use of REST APIs in a similar fashion to App Builder data objects, enabling full CRUD (Create, Read, Update, Delete) operations, custom events, and advanced UI integration.

For REST APIs that support CRUD-style operations, configuring a REST Object is an easy way to integrate an API with your App Builder app.

Configure CRUD endpoints

For a CRUD-style REST API, you must configure endpoints that allow records to undergo Create, Read, Update, and Delete operations. This typically involves setting up the following endpoints in your REST data source:

Follow the steps in Add a REST Endpoint for each CRUD operation you need, providing the appropriate Name, Endpoint, Method, and any Sample Input required for POST or PUT methods.

Create a REST Object

Once your CRUD endpoints have been configured, you can create the REST Object.

1. Select IDE > Data Servers.

2. Select your REST data server, then click Open record for the REST API. The REST API popup opens.

3. Under REST API, click Endpoints.

4. Under Web Service, click More > Super Objects. The REST Objects dialog opens.

5. Click + REST Object.

6. Enter a name your REST object (for example, Customers), then click the Save icon.

7. Click the pencil edit icon, enable Insert, Update, and Delete as appropriate, then click the Save icon again.

Configure and bind the REST object

After creating the REST Object, you must configure its Single Comp and Many Comp and bind the CRUD operations to your endpoints.

1. Configure Single and Many Comps: Open the REST Object and configure the Single Comp and Many Comp by adding the appropriate tables (for example, customers(get)/items) and columns from your Read endpoint.

2. Configure CRUD Endpoints: For each CRUD operation (Delete, Insert, Update), select the corresponding endpoint you created and bind the fields from the REST Object to the endpoint's input parameters.

You should now be able to use this REST Object in your application's UI, and add, delete, or update rows as if it were a native App Builder table.

Advanced features: Sorting, paging, and filtering

REST Objects also support advanced data interaction features. To enable them, you must configure specific parameters on your REST data source with the correct Usage Type:

• Sorting: Add a parameter with Usage Type set to Request Sort. The parameter name should match what your API expects (for example, $sort).

• Paging: Configure parameters for Request Limit, Request Offset (or Request Page Number), and Request Count. You also need to set the Usage Type of the count column in your response table to Response Total Rows.

• Filtering: Add a parameter with Usage Type set to Request Filter (OData) for OData-style filtering. The parameter name should match what your API expects (for example, $filter).