In API builder, the API response mapper shapes the data your API returns so it matches the response schema that your API consumers expect. This article is for builders who create APIs in API builder. It shows you how to open the mapper, how it differs from the mappers in flow builder, and how to map a response, with a worked example.
When to map the response
Data reaches the response step in the format of the last lookup or import, and that format often doesn't match your response schema. For example, your order system might call an identifier orderId, while your schema calls it orderNumber. The API response mapper converts the data into the schema, so consumers receive the fields and names that your API definition promises. For the structure of the definition, see OpenAPI definition structure.
Before you begin
Create the API response step and its response body schema. For how, see Configure an API response using API builder. Configure the schema first so that you can auto-populate the destination fields without schema mismatches.
How API builder mapping differs from flow builder
Import mapping, results mapping, and response mapping work in API builder as they do in flow builder. See Mapping types and versions. The API response mapper differs in these ways:
| Flow builder import mapper | API response mapper | |
|---|---|---|
| Mapper version | Mapper 1.0 or Mapper 2.0 | Mapper 2.0 only, with no version toggle |
| Destination | Fields of the destination application | Fields of the API response schema. The right pane is headed Response record { }. |
| Source data | The record from the export or previous step |
queryParams, pathParams, and the record |
| Step menu | Input filter, Pre map hook, Mapping, Post map hook, and more | Pre map hook, Mapping, and Post map hook |
| Auto-populate | Builds the destination from the application's fields | Builds the destination from the response schema |
The Success response and Error response steps both use this mapper.
Map the API response
- In API builder, open the API.
- On the Success response step, select More
> Mapping.
- Select More actions > Auto-populate destination fields to add the fields of your response schema.
- For each destination field, select the source field.
- Select Preview, or turn on Auto preview, to see the HTTP response body.
The mapper supports a JSON response schema with objects, arrays, and nested fields. Use handlebars for complex values. For the panel, settings, and array techniques, see Map data with Mapper 2.0.
Lookup caches are available in all mappers. See Lookup caches overview.
Keep the schema and mapper in sync
If you add, rename, or delete fields in the response schema after you map, the mapper's destination fields don't update for fields that already have a mapping. When you save the schema, integrator.io shows a Response schema mismatch message: "The schema may not be in sync with the response schema in Mapper. Open Mapper to auto-populate or update manually for an accurate OpenAPI spec."
To bring them back in line, open the mapper and select More actions > Auto-populate destination fields, or edit the destination fields manually. The mapper has no option to push its changes back to the schema. To change the schema, edit it in the response step.
Example: return an order number
This example uses a fictional company, ACME Chocolatiers.
ACME Chocolatiers exposes an API that lets a retailer place an order. The API request has this body:
{
"customerName": "Maple Street Cafe",
"items": [
{ "sku": "TRUFFLE-12", "qty": 4 },
{ "sku": "BAR-DARK-70", "qty": 10 }
]
}The API has an import that creates the order in ACME's order system. The order system returns an orderId and a status. A response mapping on the import saves both to the source record. See Configure response mapping.
The success response schema calls the identifier orderNumber and requires status, customerName, and an items array whose objects have sku and quantity:
{
"orderNumber": "ACME-10482",
"status": "received",
"customerName": "Maple Street Cafe",
"items": [
{ "sku": "TRUFFLE-12", "quantity": 4 },
{ "sku": "BAR-DARK-70", "quantity": 10 }
]
}Map the Success response step as follows:
| Destination field | Data type | Source |
|---|---|---|
orderNumber |
string | $.orderId |
status |
string | $.status |
customerName |
string | $.customerName |
items |
object array | $.items[*] |
items > sku
|
string | @.items.sku |
items > quantity
|
number | @.items.qty |
These source paths assume Input context is record, the default. If you set Input context to envelope, the record sits under record, so the paths start with $.record., such as $.record.orderId.
The items rows use the array technique described in Iterate over an array in Mapper 2.0.