REST object in Jitterbit App Builder
Overview
REST Objects allow App Builder developers to make use of a REST APIs in a similar fashion to App Builder Data Objects. REST Objects support the following:
- CRUD operations
- Integration with various App Builder Controls such as Multi-Row/Single-Row Panels, Lists
- Custom Events
- Sorting
- Filtering (OData style filter query string)
For REST APIs that support CRUD style operations, configuring a REST Object can be an easy way to integrate an API with your App Builder app.
CRUD endpoints
For a CRUD style REST API you will want to configure Endpoints that allow records to be Created, Read, Updated, and Deleted. In general this means setting up the following Endpoints:
Operation | Method | Example URL |
---|---|---|
Create | POST to a collection resource | https://api.example.com/rest/v1/customers |
Read | GET from a collection resource | https://api.example.com/rest/v1/customers |
Update | PUT or POST to an item resource | https://api.example.com/rest/v1/customers/<customerId> |
Delete | DELETE from an item resource | https://api.example.com/rest/v1/customers/<customerId> |
App Builder REST API example configuration
The steps below demonstrate how to configure CRUD endpoints for an App Builder REST server. In this example we will assume there exists a table such as:
Column | Attributes | Logical Type |
---|---|---|
CustomerId | Primary Key | String |
Name | String | |
DaysActive | Integer |
This REST API is exposed from the "northwinds" endpoint as a resource called "customers". Thus the URL to hit this endpoint would be:
https://api.example.com/rest/v1/northwinds/customers
Ensure you've set up the REST API on your server and created the REST Data Source before continuing.
Read endpoint
- Navigate to IDE > Data Servers > Your REST Data Server > Details
- Click + Endpoint on the Endpoints panel and configure the following information:
- Name: customers (get)
- Endpoint: customers
- Method: GET
- Click Save
- Click Discover
- Go back to the previous page
- Select your customers (get) endpoint
- Notice that there are three Output tables
- Double click the customers (get)/items table
- Set the customerId column as the Primary Key
- Ensure the columns are using the expected storage type
- Click Results and verify the returned data is as expected
Create
- Navigate to IDE > Data Servers > Your REST Data Server > Details
-
Click + Endpoint on the Endpoints panel and configure the following information
- Name: customers (insert)
- Endpoint: customers
- Method: POST
-
Sample Input - App Builder expects the input to be in the following format:
{ "item": { "customerId": "abcde", "name": "Test Customer", "daysActive": 10 } }
-
Click Save
- Click Discover
- Note that clicking Discover more than once can cause a primary key violation as the 'abcde' record will already exist on the server. If this happens, you will need to delete the existing record before Discover will work. Either delete the record on the App Builder REST API server or set up and import the "Delete" endpoint.
- Go back to the previous page
- Select your customers (insert) Endpoint
- Double click the customers (insert) table
- Set the customerId column as the Primary Key
- Set the customerId, name, and daysActive columns to Input/Output direction.
- When we create a record we pass in all three columns (Input). The App Builder REST API server echoes these columns in the returned JSON (Output). If for some reason the server echoed back a different value than we sent in (perhaps formatting a string), we will want our record to contain the returned values.
- Ensure the columns are using the expected storage type
Update
- Navigate to IDE > Data Servers > Your REST Data Server > Details
- Click + Endpoint on the Endpoints panel and configure the following information
- Name: customers (update)
- Endpoint: customers/{{item/customerId}}
- Method: POST
-
Sample Input - {{nm.ab}} expects the input to be in the following format:
{ "item": { "customerId": "abcde", "name": "Test Customer (updated)", "daysActive": 10 } }
-
Click Save
- Click Discover
- Go back to the previous page
- Select your customers (update) endpoint
- Double click the customers (update) table
- Set the customerId column as the Primary Key
- Set the customerId, name, and daysActive columns to Input/Output direction.
- Ensure the columns are using the expected storage type
REST object
Once your CRUD Endpoints have been configured, you can create the REST Object.
Create REST object
- Navigate to IDE > Data Servers > Your REST Data Server > Details
- Click More > Super Objects
- Click + REST Object
- Name your REST Object... we'll assume Customers
- Click the checkmark icon to save
- Click the pencil edit icon
- Enable Insert, Update, and Delete by clicking, as appropriate
- Click proceed or the checkmark icon to save
Configure single comp
- Click the Open Record icon for the REST Object
- Click the Single Comp icon
- Add the customers (get)/items table to the Tables panel
- Click the
"*"
button to add all of the columns - Double click the customerId column and set as a Primary Key
- Go through each column in turn and set the Logical Data Type appropriately
- Note that if you click Results before setting up the Many Comp (below) you will get a "No sequence" error message. You will need to configure the Many object first.
- Return to the REST Objects screen
Configure many comp
- Click the Many Comp icon
- Add the customers (get)/items table to the Tables panel
- Click the
"*"
button to add all of the columns - Set the Target columns to their corresponding column names
- Double click the customerId column and set as a Primary Key
- Click Results and verify that you see the appropriate data
- Return to the REST Objects screen
Configure CRUD endpoints
For each CRUD operation list, configure the Endpoint and Bindings as per the table below:
CRUD Operation | Endpoint | Binding (REST Object) | Binding (Endpoint) |
---|---|---|---|
Delete | customers (delete) | customerId | item/customerId |
Insert | customers (insert) | customerId | item/customerId |
" | " | daysActive | item/daysActive |
" | " | name | item/name |
Update | customers (update) | customerId | item/customerId |
" | " | daysActive | item/daysActive |
" | " | name | item/name |
You should now be able to click the Results button on your REST Object and add/delete/update rows.
Custom events
REST Objects can define custom events similarly to other App Builder Data Objects. To add a custom event to your REST Object you will need to:
- Create a custom event Endpoint
- Create a CRUD Rule to insert into the Endpoint
- You will need an application configured with the datasource
- Add a custom event to the REST Object
Create custom event endpoint
In {{nm.ab}}, a custom event on a table can be called by using this URL notation:
https://example.com/rest/v1/northwinds/mytable(myevent)/{{primaryKeyColumn}}
For instance if we continue using the example from above, the following Endpoint would target an "uppercase" event on the "customers" table:
customers(uppercase)/{{item/customerId}}
To set this up, do the following:
- Add an uppercase event to the {{nm.ab}} table
- Now set up the REST consuming side...
- Navigate to IDE > Data Servers > Your REST Data Server > Details
-
Click + Endpoint on the Endpoints panel and configure the following information
- Name: customers (uppercase)
- Endpoint:
customers(uppercase)/{{item/customerId}}
- Method: POST
-
Sample Input - {{nm.ab}} expects the input to be in the following format:
{ "item": { "customerId": "abcde" } }
-
Click Save
- Click Discover
- Select your customers (uppercase) endpoint
- Double click the customers (uppercase) table
- Set the customerId column as the Primary Key
- Verify the output column directions and storage types are as expected.
Create custom event CRUD rule
To call the Custom Event endpoint from your REST Object, you need to create a rule which Inserts into the Endpoint.
- Navigate to App Workbench > Data Sources > Select Your REST Data Source > Logic
- Select the customer (uppercase) Endpoint
- Click + Rule in the Rules panel and set the following
- Name: Customer (uppercase) Insert
- Purpose: CRUD
- Action: Insert
- Source/Target Data Source: Your data source
- Target: customers (uppercase)
- Click Save
- From the Tables tab:
- Select the customerId column and set the corresponding item/customerId as the target column
Create uppercase event on REST object
Now to hook it all up, we want to create the Uppercase event on the REST Object.
- Navigate to App Workbench > Data Sources > Select Your REST Data Source > Logic
- Click the Events icon for your REST Object
- On the Events panel, click + Table Event
- Set the Name to Uppercase
- Click Save
- On the Actions panel, click Register Existing
- Select the Customers (uppercase) Insert Rule
- Click Save
- Insert explicit bindings for customerId to customerId
- Go back to the Events page
- Double click the Uppercase event
- Set the Refresh scope to Row
You should be all set to call the custom event. To test, you can create a page with a Multi-Row Panel that has a button to call the event.
Sorting, paging, and filtering - Usage type
The following sections on Sorting, Paging, and Filtering describe setting Usage Type on specific Parameters. The examples given are the Parameter names App Builder uses when you access App Builder via a REST API interface. If you are accessing other external REST API server endpoints, they will have their own unique list of Parameter names and value formats for Sorting, Paging, and Filtering. Information presented in these sections is to help you understand what each of the Usage Types are and how to use them regardless of the Parameter name used by the REST API you are accessing. The App Builder API parameters used in these sections are further documented in the REST API article.
Sorting
The Usage Type that deals with sorting is Request Sort.
- Request Sort - Set this usage type on the REST parameter that the API uses for sorting. The name and content of this parameter will be defined by the API provider. For this example we use the App Builder API parameter name of
$sort
.
To enable sorting (with an App Builder REST server):
- Navigate to IDE > Data Servers
- Select your REST data source
- Click Details
- Under Web Service Parameters click + Parameter
- Set Type to Query
- Set Name to $sort
- Leave Value blank
- Set Usage Type to Request Sort
- Click check mark icon to save
You should now be able to sort any data that is fetched using this App Builder REST data source.
Paging
The Usage Types that deal with paging are Request Count, Request Limit, Request Offset, Request Page Number, and Response Total Rows.
- Request Count - Set this Usage Type on the REST parameter that the API uses to signify that you would like a total row count returned. Some APIs do not automatically return a total count in their response and require a specific parameter as a trigger. For this example we use the App Builder API parameter name of
$count
. - Request Limit - Set this Usage Type on the REST parameter that the API uses to signify that you would like a total row count returned. Some APIs do not automatically return a total count in their response and require a specific parameter as a trigger. For this example we use the App Builder API parameter name of
$limit
. - Request Offset - Set this Usage Type on the REST parameter that the API uses to signify at what row you would like to start returning data. For this example we use the App Builder API parameter name of
$offset
. - Request Page Number - Set this Usage Type on the REST parameter that the API uses to signify at what page you would like to start returning data. Some APIs use Page Number instead of Offset, or may offer both. You should define just one for your endpoint, not both. The App Builder API does not define a parameter for page number.
- Response Total Rows - Set this Usage Type on the REST parameter that the API uses to return a total row count in the response. Some APIs do not automatically return a total count in their response and require a specific parameter as a trigger. See the Request Count usage type above.
To enable paging (with an App Builder REST server):
- Navigate to IDE > Data Servers
- Select your REST data source
- Click Details
- Under Web Service Parameters click + Parameter
- Set Type to Query
- Set Name to $count
- Set Value to true
- Set Usage Type to Request Count
- Click checkmark icon to save
- Under Web Service Parameters click + Parameter
- Set Type to Query
- Set Name to $limit
- Leave Value blank
- Set Usage Type to Request Limit
- Click checkmark icon to save
- Under Web Service Parameters click + Parameter
- Set Type to Query
- Set Name to $offset
- Leave Value blank
- Set Usage Type to Request Offset
- Click checkmark icon to save
- For all Endpoints that support paging, navigate to the Endpoint table that contains the "count" parameter.
- In our example above, this would be the customers (get) table
- Set the count column's usage type to Response Total Rows
The Load More Rows button should now work for any data fetched from this Endpoint.
Panel display options
When you configure a panel to display REST Object data, there are options available in Edge Case that provide control over how the panel displays the records. You can control whether App Builder loads a set number of records along with a Load More Rows button, or if it displays a set number of records along with paging navigation controls in the toolbar region to load more records.
In addition, if the REST API configuration supports it, you can set the number of records App Builder initially displays on the panel.
To load more rows
- Navigate to the panel using the REST Object as Source
- Go to Design This Page
- Go to More > Edge Case for the panel
- Set the Paging Option to Load More Rows
To enable paging
- Navigate to the panel using the REST Object as Source
- Go to Design This Page
- Go to More > Edge Case for the panel
- Set the Paging Option to Paging
To set the number of initial records loaded
- Navigate to the panel using the REST Object as Source
- Go to Design This Page
- Go to More > Edge Case for the panel
- Set Rows Per Request to the numeric value you want to initially load
Filtering
The Usage Types that deals with filtering are Request Filter and Request Filter (OData). Set this usage type on the REST parameter that the API uses for filtering. Request Filter is for simple filtering where Request Filter (OData) is for filtering using the OData standard. This standard defines different filter conditions. The App Builder API uses OData style filter as used in our example. Check your specific API docs to see if OData filtering is supported before using it. More information about OData filtering can be found here in this REST API recommendations article.
To enable filtering (with an App Builder REST server):
- Navigate to IDE > Data Servers
- Select your REST data source
- Click Details
- Under Web Service Parameters click + Parameter
- Set Type to Query
- Set Name to $filter
- Leave Value blank
- Set Usage Type to Request Filter (OData)
- Click checkmark icon to save
You should now be able to filter any data that is fetched using this App Builder REST data source.
Filtering via a REST Service supports the following:
Operators
eq
– Equalneq
– Not equalgt
– Greater Thange
– Greater Than or Equallt
– Less Thanle
– Less Than or Equal
Limitations
- No arithmetic operators
- No or/not logical operators
- No grouping operators
- No query functions
- No parameter aliases