Skip to Content

REST API in Jitterbit App Builder

Overview

REST is web service architectural style. REST defines a set of stateless operations which can be performed on resources. App Builder allows developers to publish data objects as REST resources. Consumers can perform operations on those resources which translate to data object event invocations.

Applications as web services

The App Builder design environment is organized around the concept of an application. Although applications typically describe a user interface, applications have several properties that are also applicable to web services:

  • Applications provide access to multiple data sources.
  • Groups are granted privilege to an application.

App Builder extends the concept of an application to include web services. Specifically, developers have the ability to define an endpoint for an application. For example, the endpoint for the Sales application might be sales. The corresponding URI might look like this:

  • https://example.com/App Builder/rest/v1/sales

Data objects as resources

The organizing principal of REST is the concept of a "resource". Resources can represent a collection of items or a single item. In App Builder terms, a data object is represented as a collection with individual rows represented as items in that collection.

Like the service itself, the developer determines the data object endpoint. For example, the Customers data object might have an endpoint of customers. In which case, the corresponding URI might look like this:

  • https://example.com/App Builder/rest/v1/sales/customers

The URI for a specific item (row) might look like this:

  • https://example.com/App Builder/rest/v1/sales/customers/b603b276-a9bf-4328-88ff-8994176c38d1

The primary key appears in the URI path.

Composite primary keys can be specified by separating the keys with a comma:

  • https://example.com/App Builder/rest/v1/sales/customers/abc,def

Events as HTTP methods

REST defines a set of operations corresponding to HTTP methods. App Builder's REST API supports the following HTTP methods:

  • GET /collection - Retrieves the items within a collection. This maps to the Filter event.
  • POST /collection - Adds an item to the collection. This maps to the Insert event.
  • GET /collection/item - Retrieves a single item from the collection. This maps to the Filter event.
  • POST /collection/item - Updates an item in the collection. This maps to the Update event.
  • DELETE /collection/item - Deletes an item from the collection. This maps to the DELETE event.

App Builder's REST API does not currently support the following HTTP methods:

  • HEAD - The HEAD method allows consumers to retrieve the HTTP response headers. At the moment, App Builder does not support this operation.
  • OPTIONS - The OPTIONS method allows consumers to determine which methods are supported.
  • PUT (collection or item) - The PUT method allows consumers to create an item (when addressing the collection) or update an item (when addressing the item). However, since PUT is idempotent, it must include all fields. This limits its usefulness in many scenarios.
  • PATCH - The PATCH method allows consumers to update part of an item. This is currently supported via a POST. Typically, PATCH uses a patch-specific format, complicating the implementation.

Not all App Builder events can be published:

  • New - App Builder's New event creates a non-persistent row, applying any defaults. Consumers cannot invoke the New event.
  • Change - Interactions with the UI invoke a pseudo-event which runs defaults and validations without persisting changes. Consumers cannot simulate the Change event.
  • User-defined events - In addition to the intrinsic events, developers can define their own events. Currently, these cannot be mapped to resource methods.

RESTful design principals

To the extent possible, App Builder's REST API follows these RESTful principals:

  • Services are stateless.
  • Endpoints are modeled as resources.
  • GET operations are safe. A "safe" operation is one that does not have side effects. For instance, retrieving a list of customers does not change the list of customers.
  • DELETE operations are unsafe, but idempotent. However, whereas the first (successful) request to delete an item will return a 200 status code, the second request will return a 404.
  • POST operations are neither safe nor idempotent. Because of this, POST operations may contain partial data.
  • HTTP status codes indicate whether an error occurred.
  • Media types are used to perform content negotiation. At the moment, however, App Builder only supports JSON (application/json) and UTF-8.

App Builder does not adhere to all RESTful principals:

  • Resource responses are wrapped in an envelope. This allows App Builder to include additional information, such as event messages and validation results.
  • Resource responses are not hypermedia: they do not include links to other resources.

REST URI conventions

At the collection level, the GET method supports the following features:

  • Paging via $offsetand $limit parameters. The default limit is 10; the maximum limit is 100.
  • Sorting via a $sort parameter. The $sort parameter can take a comma-delimited list of field names. Prefix the field name with a dash (-) to sort the field in descending order. For example, the sort specification $sort=-country,companyName would sort the collection by country, descending, and companyName, ascending.
  • Selection via a $fields parameter. The $fields parameter can take a comma delimited list of field names (e.g. $fields=customerId,country). Specific the asterisk (*) to retrieve all resource fields (e.g. $fields=*).
  • Searching by keyword via a $q parameter. The $q parameter takes in a string and tries to match against column values. Any table rows which have at least one column value that contains the $q parameter as a sub-string will be returned (e.g. $q=miami). Note that the matching is case-insensitive.
  • Filtering via simple equality comparisons. To limit the results, specify the field name and value (e.g. countryId=USA).
  • Count via the $count parameter. By default, App Builder will not return a total count of the number of items within the collection. To include the count, append the count parameter (e.g. $count=true).

Conventions for parameters:

  • Parameters that refer to resource fields are not prefixed.
  • Parameters that operate on the collection itself are prefixed with a dollar sign ($).

Validation

An event may return one or more errors, warnings, or informational validation results as part of the response. Each validation will include a validationId, a message (defined in the IDE), and the severity of the validation ("error", "warning", "information").

If you would like to bypass a warning, include the provided validationIds as the value of a X-App Builder-Ignore-Warnings header in a new request to the endpoint.

For example, for the following response:

{
  "item": {
    "contactId": "8d20b593-aa41-4bbb-8bee-58f17ac2bf32",
    "name": "Company Name"
  },
  "message": null,
  "validations": [
    {
      "validationId": "8d20b593-aa41-4bbb-8bee-58f17ac2bf32",
      "message": "32 emails will be sent, are you sure?",
      "severity": "warning"
    },
    {
      "validationId": "6bad40b7-2504-4243-9e90-100bcc7bfd13",
      "message": "No subject was provided, use default?",
      "severity": "warning"
    }
  ],
  "status": 400
}

A new request (to the same endpoint, and same data) would need to include the following header information:

X-App Builder-Ignore-Warnings: "8d20b593-aa41-4bbb-8bee-58f17ac2bf32", "6bad40b7-2504-4243-9e90-100bcc7bfd13"

Known issues and limitations

  • Binary fields such as files are not currently supported.
  • The only supported content type is JSON (application/json).
  • The only supported text encoding is UTF-8.
  • Collections are limited to returning 100 items at a time.
  • Composite primary keys can not contain commas.
  • Only filtering via simple equality comparisons is supported.