JSON request body mapping is used to map incoming records into body parameters. It must be populated when using multiple input ports.

Example of a static request body - you can use parameter references instead of static values. Note that Static request body cannot be combined with JSON request body mapping.

This is the primary way of parsing data from API responses. This mapping allows you to visually map and process complex API responses based on the response schemas provided in the OpenAPI specification. The mapping allows you to parse each response type with its own mapping ensuring that the data you need is sent to correct output ports.

The response types are distinguished based on their HTTP response code - i.e., you can map success response 200 in a different way than failure (HTTP 400) etc.

To specify the mappings, start in the Select response codes to map panel in the upper-left corner of the Mapping tab. This panel allows you to add mappings for different response codes as defined in the OpenAPI specification for the API you are calling. Start with the Response type and work your way down to fill in additional details to create the mapping.

When the API response is parsed, the more specific codes are preferred instead of the ranges. For example, consider two mappings one of which is for "400-499", and the other one is for "404". This will effectively behave as if you wrote the mappings as "400-403,405-499" and "404". This approach allows you to easily cover many status codes while specifically cherry-picking the interesting ones that need to be handled differently.

Each mapping can extract data from the response to multiple output ports. This works just like the mapping in the JSONExtract component. As an example, the following screenshot shows mapping of Petstore API and maps responses to four different ports. Ports are shown in the mapping tree just after the filter - so "HTTP_404 [1:1] (port 3)" means that response with status code 404 will be mapped to port 3 (and it is a 1:1 mapping of a single entity). The mapping maps the response like this:

In this example, status codes different from 200, 201, or 404 will not be matched and therefore the Default output mapping will be used instead.

The Default output mapping is used whenever the response type (as defined by its status code) is not covered by any filters in the JSON response mapping. This allows you to map the complex and interesting responses in a simple, visual way via the JSON response mapping and handle all the other cases (even unknown responses and errors) with the Default output mapping.

Default output mapping is specified as a transformation that allows you to use CTL and provides access to the response, its HTTP status code and even headers or component attributes. This gives you the ability to process all parts of the response as needed.

The Default output mapping will also apply in cases where the API call failed on the network level or due to other runtime error - e.g., target server was not found, the call timed out and so on. In such cases, the errorMessage field will provide additional information about the failure. This is similar to the approach used in HTTPConnector’s output mapping.

The following example sends all responses (not covered by the JSON response mapping, see its example) to port 4:

If the Default output mapping is not defined and a response has status code ≥ 300 or if an error is encountered when calling the API, the component will fail and the error message will be written to the graph log.

Consult your specific API documentation to determine the supported pagination type. Once you’ve identified the type, select the corresponding option from the list and populate the required configuration fields with the appropriate values from your API documentation.

See below for an example configuration for CloverDX REST API, which uses the Offset and limit pagination. This configuration will return 25 results per page, starting from the very beginning (index 0), and it limits the total number of requests to 100.

Below is an example configuration for the X REST API, which uses the Token-based pagination. This configuration will return 25 results per page, and it does not limit the total number of requests.