Crafting a well-structured API response schema is crucial for ensuring consistency, clarity, and ease of use for developers consuming the API. An adequately designed schema helps standardize responses, making it easier to parse and handle data efficiently across different applications. It improves error handling, data validation, and future scalability, ensuring that new features or updates do not break existing implementations. A good response schema enhances readability by clearly defining fields, data types, and nested structures, reducing confusion and minimizing integration issues. Ultimately, a well-crafted schema leads to a more reliable and developer-friendly API.
Things to consider while configuring your API response:
- Configure your API request
- Add a lookup or import: This is particularly important because you can't create your business logic without a lookup or import to create, read, update, or delete data.
- Add branches
You can use the Response picker, an out-of-the-box branching router, to define multiple response nodes that seamlessly handle different response codes and structures.
The backend sets a true or false boolean flag called Success to indicate whether the API succeeded. This flag cannot be edited; however, you can configure your API's behavior using the Response picker to set record flow conditions. You don't have to use the flag to determine whether the API succeeded, but we recommend it.
Two branches are automatically configured: The Success response executes when the Success flag is true, and the Error response executes when the Success flag is false.
For example, if the Success flag in the backend is true, the Success response branch's record flow conditions say that the API should return a successful API response. You can see this in the screenshot below; if Success equals true, the Success response branch will execute.
You can edit how the Success response and Error response branches execute by editing the record flow conditions. For example, if you'd like to return a response based on a specific error or a test mode response instead of the Success boolean flag. Don't forget you can add more responses and specify their record flow conditions.
There are some rules and requirements to be aware of when using the Response picker:
- The Response picker is added by default, and its name cannot be updated.
- There are always two default branches that lead to Success and Error response nodes, which cannot be removed.
- The Response picker's default names are "Success response" and "Error response;" however, you can rename them. If you add another response node, the name will be blank by default.
- You can add new branches, which will automatically add new response nodes.
Name* (required): Name your API response so that you can easily reference it from other parts of the application.
Description* (required): Describe your API response so that users can quickly understand what it is doing without reading through all the configuration fields.
HTTP status code (required): Select an HTTP status code from the drop-down. Currently, you cannot add codes. 200 and 500 are selected by default for the success and error response steps, respectively.
| Status code | Message |
|---|---|
| 100 | Continue |
| 101 | Switching Protocols |
| 102 | Processing |
| 103 | Early Hints |
| 200 | OK |
| 201 | Created |
| 202 | Accepted |
| 203 | Non-Authoritative Information |
| 204 | No Content |
| 205 | Reset Content |
| 206 | Partial Content |
| 207 | Multi-Status |
| 208 | Already Reported |
| 226 | IM Used |
| 300 | Multiple Choices |
| 301 | Moved Permanently |
| 302 | Found |
| 303 | See Other |
| 304 | Not Modified |
| 305 | Use Proxy |
| 307 | Temporary Redirect |
| 308 | Permanent Redirect |
| 400 | Bad Request |
| 401 | Unauthorized |
| 402 | Payment Required |
| 403 | Forbidden |
| 404 | Not Found |
| 405 | Method Not Allowed |
| 406 | Not Acceptable |
| 407 | Proxy Authentication Required |
| 408 | Request Timeout |
| 409 | Conflict |
| 410 | Gone |
| 411 | Length Required |
| 412 | Precondition Failed |
| 413 | Payload Too Large |
| 414 | URI Too Long |
| 415 | Unsupported Media Type |
| 416 | Range Not Satisfiable |
| 417 | Expectation Failed |
| 418 | I'm a Teapot (RFC 2324) |
| 421 | Misdirected Request |
| 422 | Unprocessable Entity |
| 423 | Locked |
| 424 | Failed Dependency |
| 425 | Too Early |
| 426 | Upgrade Required |
| 428 | Precondition Required |
| 429 | Too Many Requests |
| 431 | Request Header Fields Too Large |
| 451 | Unavailable For Legal Reasons |
| 500 | Internal Server Error |
| 501 | Not Implemented |
| 502 | Bad Gateway |
| 503 | Service Unavailable |
| 504 | Gateway Timeout |
| 505 | HTTP Version Not Supported |
| 506 | Variant Also Negotiates |
| 507 | Insufficient Storage |
| 508 | Loop Detected |
| 510 | Not Extended |
| 511 | Network Authentication Required |
You'll need some familiarity with JSON to create your response body successfully. After you create your response body, you'll need to map your API response. There are various example response bodies at the end of this article.
You can import JSON to generate the schema or click + to add fields manually. The field data types available are:
-
string -
number -
boolean -
object -
array
Define the custom headers of your API endpoint. HTTP headers are essential in API responses because they provide metadata, such as authentication credentials, content format, and caching instructions, ensuring secure and efficient communication between the client and server. Using headers like Authorization, Content-Type, and Accept helps enforce security, improve performance, and ensure compatibility with the API’s expected request and response formats. You can use handlebars expressions to define the custom header.
Warning
The only Authorization header allowed at this time is Token. However, you can use other authorization headers through advanced API Management configurations.
Relative URI: /stores/
This API includes one request, one lookup, and two responses.
{
"method": "GET",
"endpoint": "/stores/",
"headers": {
"Authorization": "Bearer <your_api_token>",
"Content-Type": "application/json"
},
"query_parameters": {
"limit": 10,
"offset": 0,
"sort": "name",
"order": "asc"
}
}A lookup allows you to process the request data and use it to search ("look up") the information for all pet stores. In this lookup step, you'll want to configure the request mapping so the data your API consumer sends is properly mapped to your database.
{
"status": "success",
"data": {
"stores": [
{
"id": 123,
"name": "Happy Paws Pet Store",
"location": "123 Main St, Springfield, IL",
"phone": "+1-555-1234",
"hours": {
"monday": "8 AM - 6 PM",
"tuesday": "8 AM - 6 PM",
"wednesday": "8 AM - 6 PM",
"thursday": "8 AM - 6 PM",
"friday": "8 AM - 6 PM",
"saturday": "9 AM - 3 PM",
"sunday": "Closed"
}
},
{
"id": 124,
"name": "Furry Friends Pet Store",
"location": "456 Elm St, Austin, TX",
"phone": "+1-555-5678",
"hours": {
"monday": "9 AM - 5 PM",
"tuesday": "9 AM - 5 PM",
"wednesday": "9 AM - 5 PM",
"thursday": "9 AM - 5 PM",
"friday": "9 AM - 5 PM",
"saturday": "10 AM - 2 PM",
"sunday": "Closed"
}
}
]
}
}
This API includes one request, three lookups, and two responses. The request retrieves details of a specific pet and its health records from a store.
Relative URI: /stores/:storeId/pets/:petId,
-
storeId(123): Represents the specific store (vet office or pet store). -
petId(101) → Unique identifier for the pet.
{
"method": "GET",
"endpoint": "/stores/123/pets/101",
"headers": {
"Authorization": "Bearer <your_api_token>",
"Content-Type": "application/json"
}
}A lookup allows you to process the request data and use it to search for ("look up") a dog. In this lookup step, you'll want to configure the request mapping so the data your API consumer sends is properly mapped to your database.
A lookup allows you to process the request data and use it to search for ("look up") a cat. In this lookup step, you'll want to configure the request mapping so the data your API consumer sends is properly mapped to your database.
A lookup allows you to process the request data and use it to search for ("look up") the dog or cat's health records. In this lookup step, you'll want to configure the request mapping so the data your API consumer sends is properly mapped to your database.
{
"status": "success",
"data": {
"id": 101,
"name": "Buddy",
"age": 3,
"breed": "Labrador Retriever",
"weight_kg": 28.5,
"store": {
"id": 123,
"name": "Happy Paws Pet Store",
"location": "123 Main St, Springfield, IL",
"phone": "+1-555-1234"
},
"owner": {
"id": 1001,
"name": "John Doe",
"phone": "+1-555-1234"
},
"last_visit": "2024-01-15",
"vaccinations": ["Rabies", "Distemper", "Parvovirus"]
}
}
This request creates a new pet using the relative URI: /stores/:storeId/pets/. It includes one request, one import, four branches, and four responses. Each branch ends in a different response node.
Note
In this example, the API request data and the API response data are identical. In practice, the API request data may include different or additional fields. This is where mapping helps.
- Uses
POST /stores/123/pets/to create a new pet instore ID 123. - Includes detailed pet information such as microchip ID, breed information, and medical history.
{
"name": "Buddy",
"age": 3,
"breed": "Labrador Retriever",
"weight_kg": 28.5,
"microchip_id": "982000411234567",
"owner": {
"id": 1001,
"name": "John Doe",
"phone": "+1-555-1234"
},
"last_visit": "2024-01-15",
"vaccinations": ["Rabies", "Distemper", "Parvovirus"],
"medical_history": [
{
"date": "2023-06-10",
"condition": "Ear infection",
"treatment": "Antibiotics"
},
{
"date": "2022-09-05",
"condition": "Allergic reaction",
"treatment": "Antihistamines"
}
],
"dietary_preferences": {
"food_brand": "Hill’s Science Diet",
"meal_frequency": 2,
"allergies": ["Chicken", "Soy"]
},
"exercise_routine": {
"daily_walks": 2,
"walk_duration_minutes": 30,
"favorite_activity": "Fetch"
}
}
An import step allows you to take the request data provided above and send it to your database, thus adding the pet to the database. In this import step, you'll want to configure the import and response mapping so the data your API consumer sends is properly mapped to your database.
This is one branch ending in a successful pet creation. You'll want to add API response schema mapping here to include the unique ID and any other data you'd like to include in your response.
-
201 Created→ Indicates successful creation. - Includes a unique ID (
101) for the newly created pet. - Returns a timestamp (
created_at) to confirm when the record was created.
{
"status": "success",
"message": "Pet record created successfully.",
"data": {
"id": 201,
"name": "Buddy",
"age": 3,
"breed": "Labrador Retriever",
"weight_kg": 28.5,
"microchip_id": "982000411234567",
"store": {
"id": 123,
"name": "Happy Paws Veterinary Clinic",
"location": "123 Main St, Springfield, IL"
},
"owner": {
"id": 1001,
"name": "John Doe",
"phone": "+1-555-1234"
},
"last_visit": "2024-01-15",
"vaccinations": ["Rabies", "Distemper", "Parvovirus"],
"medical_history": [
{
"date": "2023-06-10",
"condition": "Ear infection",
"treatment": "Antibiotics"
},
{
"date": "2022-09-05",
"condition": "Allergic reaction",
"treatment": "Antihistamines"
}
],
"dietary_preferences": {
"food_brand": "Hill’s Science Diet",
"meal_frequency": 2,
"allergies": ["Chicken", "Soy"]
},
"exercise_routine": {
"daily_walks": 2,
"walk_duration_minutes": 30,
"favorite_activity": "Fetch"
},
"created_at": "2025-02-10T14:30:00Z"
}
}This is one branch ending in a "bad request" response.
{
"status": "error",
"message": "Missing required fields: name, breed"
}This is one branch ending in an "unauthorized" response.
{
"status": "error",
"message": "Unauthorized. Invalid API token."
}
Here’s an example of a composite API. This request performs multiple actions in a single API call. The relative URI in this case is /v1/composite . This API enables you to:
- Checks if the pet exists in the system using its
microchip_id. - A new pet record is added to the system if the pet does not exist.
- If the pet exists, it orders pet food based on the pet’s dietary preferences.
Note
In this example, the API request data and the API response data are identical. In practice, the API request data may include different or additional fields. This is where mapping helps.
- Methods (
POST) – Defines the HTTP method to be used. -
Requests Array – Specifies each action that can be performed:
- Get Pet (
getPet) – Fetches pet details using apetId. - Create Pet (
createPet) – Creates pet details using the response fromgetPet. - Create Order (
createOrder) – Places an order only after the pet is updated.
- Get Pet (
- Dependencies (
dependsOn) – Ensures correct execution order. - Aggregated Response – Combines all individual responses into a single output.
{
"transactions": [
{
"id": "get_pet",
"method": "GET",
"endpoint": "/pets",
"query_parameters": {
"microchip_id": "982000411234567"
}
},
{
"id": "create_pet",
"method": "POST",
"endpoint": "/pets",
"dependsOn": "get_pet",
"condition": "not_found",
"body": {
"name": "Buddy",
"age": 3,
"breed": "Labrador Retriever",
"weight_kg": 28.5,
"microchip_id": "982000411234567",
"owner": {
"id": 1001,
"name": "John Doe",
"phone": "+1-555-1234"
},
"last_visit": "2024-01-15",
"vaccinations": ["Rabies", "Distemper", "Parvovirus"],
"medical_history": [
{
"date": "2023-06-10",
"condition": "Ear infection",
"treatment": "Antibiotics"
}
],
"dietary_preferences": {
"food_brand": "Hill’s Science Diet",
"meal_frequency": 2,
"allergies": ["Chicken", "Soy"]
}
}
},
{
"id": "order_pet_food",
"method": "POST",
"endpoint": "/stores/123/orders",
"dependsOn": "get_pet",
"condition": "success",
"body": {
"order_type": "pet_food",
"pet_id": "$get_pet.id",
"store_id": 123,
"food_brand": "$get_pet.dietary_preferences.food_brand",
"quantity_kg": 5,
"order_date": "2025-02-10T14:30:00Z",
"status": "Processing",
"delivery_time": "2025-02-11T10:00:00Z",
"special_requests": "Grain-free variant if available"
}
}
]
}A lookup step allows you to retrieve pet details. In this lookup step, you'll want to configure the request mapping so the data your API consumer sends is properly mapped to your database.
An import step allows you to take the request data provided above and send it to your database, thus adding a pet. In this import step, you'll want to configure the import and mappings so the data your API consumer sends is correctly mapped to your database.
An import step allows you to take the request data provided above and send it to your database, thus creating an order for a pet. In this import step, you'll want to configure the import and mappings so the data your API consumer sends is correctly mapped to your database.
This is one branch ending in a successful response. You'll want to add API response schema mapping here to include the unique ID and any other data you'd like to include in your response.
-
201 Created→ Indicates successful creation. - Includes a unique ID (
101) for the newly created pet. - Returns a timestamp (
created_at) to confirm when the record was created.
{
"status": "success",
"transactions": [
{
"id": "get_pet",
"status": "success",
"code": 200,
"message": "Pet found in the system.",
"data": {
"id": 201,
"name": "Buddy",
"age": 3,
"breed": "Labrador Retriever",
"weight_kg": 28.5,
"microchip_id": "982000411234567",
"owner": {
"id": 1001,
"name": "John Doe",
"phone": "+1-555-1234"
},
"dietary_preferences": {
"food_brand": "Hill’s Science Diet",
"meal_frequency": 2,
"allergies": ["Chicken", "Soy"]
}
}
},
{
"id": "create_pet",
"status": "skipped",
"code": 304,
"message": "Pet already exists. No need to create a new record."
},
{
"id": "order_pet_food",
"status": "success",
"code": 201,
"message": "Pet food order placed successfully.",
"data": {
"order_id": 5012,
"pet_id": 201,
"store_id": 123,
"food_brand": "Hill’s Science Diet",
"quantity_kg": 5,
"order_date": "2025-02-10T14:30:00Z",
"status": "Processing",
"delivery_time": "2025-02-11T10:00:00Z",
"special_requests": "Grain-free variant if available"
}
}
]
}This is one branch ending in a "bad request" response.
{
"status": "error",
"message": "Missing required fields: name, breed"
}This is one branch ending in an "unauthorized" response.
{
"status": "error",
"message": "Unauthorized. Invalid API token."
}