An API request is essential as it provides a clear blueprint for the structure and format of data exchanged between systems. It ensures consistency by defining required fields, data types, and validation rules, which minimizes errors and simplifies troubleshooting. By establishing this standard, you can easily create, test, and maintain reliable APIs.
To build your API, you'll need to configure your API request. Configuring an API request allows you to:
-
Send data to another system (e.g., logging a new ticket in a support system).
-
Update or delete records (e.g., modifying an existing user profile in a database).
-
Automate workflows by integrating systems (e.g., syncing data between a CRM and a ticketing platform).
Configuring API requests ensures efficient data exchange, improves system interoperability, and streamlines your business processes.
A composite API allows you to perform multiple related actions in a single call, representing a unit of business functionality. Instead of making separate API calls for each step, a composite API orchestrates them within one request, simplifying integration and ensuring consistency. Common use cases include placing an order, onboarding a customer, or processing a loan application, where multiple dependent operations must be executed together.
POST is often used because composite APIs involve executing multiple operations in a single request, including retrieving, creating, updating, or deleting data across different endpoints. Since POST allows sending a structured request body, it enables the API to bundle multiple actions and process them sequentially or as a batch.
GET aggregates or retrieves multiple data sources in a single request. For example, retrieving pet details and storing the information at once. It's helpful in APIs that require:
-
Faster data retrieval – Retrieving multiple resources in one call.
-
Reduced client-side processing – The server aggregates the data before responding.
-
Better API efficiency – Fewer round trips between client and server.
Creating a composite API requires a well-made request body and multiple lookups/imports.
Name* (required): Name your API request so that you can easily reference it from other parts of the application.
Description* (required): Describe your API request so that users can quickly understand what it is doing without reading through all the configuration fields.
HTTP method* (required): Choose an HTTP method. An API can only support one HTTP method.
-
Use the
GETmethod if the API is meant to retrieve some data -
Use the
POSTmethod to create a new resource -
Use the
PUTmethod to update a resource -
Use the
PATCHmethod to partially update an existing resource -
Use the
DELETEmethod to delete a specific resource
Relative URI* (required): Define the Relative URI or the path of your API endpoint. The field value should start with a forward slash (/) and cannot be empty. The URI is relative to https://api.integrator.io/apis/<version>.
The API endpoint URL is publicly accessible and may be identical to an existing one in a different account. However, only users with a valid API token can successfully invoke it, ensuring secure access for the intended audience. The endpoint URL must be unique within your account – meaning that you can't have two identical endpoint URLs enabled simultaneously in the same account.
The API version is based on the version you entered when you created the API. You can change this at → → → .
To add a path parameter, add a colon (:) followed by the path parameter’s name. You can add more than one path parameter. For example, /stores/:storeId/pets/:petId. To add a query parameter, use the Query parameters section.
Path parameters are dynamic segments in an API URL that specify a resource's identity within an endpoint. They are typically represented with a colon (:) in RESTful APIs. For example, in the URL /stores/:storeId/pets/:petId, the values of storeId and petId determine which store and pet are being accessed.
Unlike query parameters, which filter or modify requests, path parameters are essential for identifying specific resources. They are required in most cases to help make API endpoints more structured and intuitive. This section displays all the path parameters you included in the relative URI. This section is read-only, but you can make changes by modifying the relative URI.
Use query parameters to allow API consumers to fetch and filter relevant data. For example, when retrieving a list of dogs in a pet store, you can use query parameters to filter by breed, age, and vaccination status.
Query parameters are optional. Any errors will be ignored if your API consumer doesn't enter a query parameter or enters the wrong data type for a query parameter.
You can choose from the following data types: String (default), Number, or Boolean.
To display the query parameters in the cURL command, see → . cURL is a command-line tool that sends HTTP requests, making it useful for testing APIs. It supports various HTTP methods (GET, POST, PUT, PATCH, and DELETE) and allows headers, authentication, and data payloads.
Define the custom headers of your API endpoint. HTTP headers are essential in API requests because they provide metadata, such as authentication credentials, content format, and caching instructions, ensuring secure and efficient communication between the client and server. Headers like Content-Type and Accept help enforce security, improve performance, and ensure compatibility with the API’s expected request and response formats. Only letters, numbers, hyphens, and underscores are supported.
The Celigo platform automatically includes token authentication for APIs. You don't have to add an Authorization header to invoke an API with a token. Learn more about authentication and invoking an API in a third-party service (ex. Postman). You can use other types of authentication (like JWT and OAuth 2.0) with API Management.
Define your API request body’s schema. You can upload a JSON file to automatically generate the schema or click + to add fields manually. The field data types are string, number, boolean, object, or array. The schema can include arrays, objects, nested fields, etc. The supported media type is JSON. You'll need some familiarity with JSON to create your request body successfully. There are various examples of HTTP request bodies at the end of this article.
Important
The request payload supports only one record at a time.
The mock API request is auto-populated with sample data; however, populating your own mock data can be helpful.
Click Edit mock API request to update your mock API request. You can use this to preview API requests and the parsed output, modify the data to test API invocation scenarios, or help with API request configurations and reset it to the integrator.io canonical format. Mock API request data is stored forever, so do not store personal information. You must use valid JSON since the Celigo platform automatically checks for valid JSON structures.
Click Reset to canonical stub to reset the mock API request. Any changes made to mock data will be removed.
Click Preview to review the HTTP request and the parsed output. The Parsed output is selected by default and displays the JSON payload you'll see in subsequent Transformations.
After configuring the mock API request and clicking Preview, the API request can be viewed in cURL format. Click Copy to copy the data for importing into Postman or other tools to invoke the API.
The Celigo platform performs a basic validation test against the API request during runtime, and an error response is returned if the validation fails.
Basic validation errors, such as 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 413 (Payload Too Large), and 415(Unsupported Media Type), are returned to the API consumer even before the API starts running.
Basic validation is performed in the following scenarios:
-
If the JSON format is incorrect
-
If the HTTP request body is not sent when required (e.g., during a
POSTrequest) -
If the path parameters are not listed, the Celigo platform will return a
404 - Not found, provided it doesn’t match with any other API endpoints
Advanced API request validation (schema validation) is available through API Management using the Validate request policy.
Use your request debug logs to view bugs and errors specific to your API request before you perform a test run. You can sort your request debug logs by Time, Method, and Response code.
Learn more about testing and debugging your API.
Use Transformations to add incoming path parameters, query parameters, and headers and generate a source record required for the downstream steps. Define one or more transformation rules to rename fields, remove fields, and/or structurally optimize records returned by the API request node before the records are passed to the next step in the API.
In the right column, select the field you want to extract from your API request data. Then, in the left column, enter the field name to generate. You must extract all the fields you want to keep, even if you do not modify them.
Transformation rules are applied in the order they appear; drag and drop them to change the order.
After configuring your API request, you can Save and close it. Then, you can move on to any of the following:
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.
-
-
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."
}