Articles in this section

Mapping data in API builder

This article describes the types of mappings available but primarily focuses on API response mapping and the minor differences between using the Flow Builder Mapper and the API Builder Mapper.

Tip

Configure your API response schema before you start mapping. This way, you can use the Auto-map feature without encountering response mismatches.

Why map your API response

You can structure your API response data to conform to the OpenAPI definition structure required for your business purpose. Even in cases where your API consumer has the OpenAPI specs that the Celigo platform provides, they may make a mistake or not follow the schema properly. Additionally, your lookups or imports may change the data's format, leading to irregularities between your consumer's data and the final output. Mapping allows you to ensure the data matches your final output.

For example, let's say you create a new pet. The pet data sent can include name, birthday, vaccination records, food brand, etc. Once the API consumer sends the data, it passes to an import step to add the new pet to your pet store's database. Here, you can map your import and response data.

After you've mapped the import data, it will be sent downstream to the API response. However, at this point, the data is in the format your database outputs, which might not suit your API response needs. After creating your API response, you can easily map the data from the database structure into the format required by your response schema. For example, the database output may include a petId. You want to send the petId back to the consumer in the response, but your schema may call it a petNumber instead of a petId. Using the API response mapper, you can map the petId from the database to the petNumber in your response schema and send it in the Success response.

Mapping types

There are four types of mapping: import, response, results, and API response. Mapping data defines how your records are compared, merged, or transformed between lookups, imports, and your final API response schema. Click the mapping.svg icon to open the mapper. Lookup caches are available to use throughout API builder.

  • Import mapping (import): Import mapping defines how the provided data relates to your import destination record data. You can use Mapper 1.0 or Mapper 2.0 to configure import mappings.

    import_mapping.png
  • Response mapping (import): You can add response mappings to capture data returned from an import within your API. Response mappings allow you to insert the response data of an import back into your source record so that you can reference that data in subsequent steps of your API.

    For example, suppose an application automatically assigns pet IDs to newly imported pets and includes them in the response. In that case, you can add those field values to the source record for future use, like sending the pet ID to the API consumer after it's created.

    response_mapping.png
  • Results mapping (lookup): Results mapping is similar to response mapping, but instead of returning the response after an import, results mapping allows you to merge the resulting records returned by a lookup in your API back into the provided data. The returned lookup records can be used later in the API.

    results_mapper.png
  • API response mapping (API response): Map your source records to the API response schema records.

    For example, to create a new pet, you must map the source record you sent (e.g., name, birthday, vaccinations) to the response you'll send after the pet is created. The response schema in this mapper is automatically generated based on the API response body schema in the API response.

    Tip

    You can change the schema in the Mapper and sync the changes to the API response schema for an accurate OpenAPI spec.

    Success_response_mapping.png

Before you begin

Create your API response.

Map your API response

In the API response step, click +Mapping (mapping.svg) to open the Mapper.

Success_response_mapping.png

The schema can include arrays, objects, nested fields, etc., and the supported media type is JSON. You can use handlebars to supplement your mappings in cases where you have complex data requirements.

Click Auto preview or Preview to view the HTTP response body and other details you've added to your API response.

For more on utilizing Mapper 2.0, see:

Response schema mismatch

If you add, update, or delete fields in the API response step after completing your mappings, the HTTP response body schemas will not sync. In this case, you'll receive a warning to open the Mapper and click Auto-populate response fields or manually make changes to generate an accurate OpenAPI spec.

API builder examples

Get all pet stores

Relative URI: /stores/

This API includes one request, one lookup, and two responses.

Get_pet_stores_api.png

API request

{
  "method": "GET",
  "endpoint": "/stores/",
  "headers": {
    "Authorization": "Bearer <your_api_token>",
    "Content-Type": "application/json"
  },
  "query_parameters": {
    "limit": 10,
    "offset": 0,
    "sort": "name",
    "order": "asc"
  }
}

Lookup: Get all pet stores

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.

API response: Successful retrieval of pet stores

{
  "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"
        }
      }
    ]
  }
}

API response: 400 Bad Request (Invalid Query Parameters)

{
  "status": "error",
  "code": 400,
  "message": "Invalid query parameters: 'page_size' must be a positive integer.",
  "errors": {
    "page_size": "Must be greater than 0"
  }
}

Get a pet

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,

Get_a_pet_API_builder.png

API request

  • 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"
  }
}

Lookup: Get a dog

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.

Lookup: Get a cat

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.

Lookup: Get health records

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.

API response: Successful retrieval of pet

{
  "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"]
  }
}

API response: 400 Bad Request (Invalid Query Parameters)

{
  "status": "error",
  "code": 400,
  "message": "Invalid query parameters: 'page_size' must be a positive integer.",
  "errors": {
    "page_size": "Must be greater than 0"
  }
}

Create a new pet

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.

API request body

  • Uses POST /stores/123/pets/ to create a new pet in store 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"
  }
}

 

Import: Create a new pet

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.

API response: Successful Pet Creation

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"
  }
}

API response: Bad Request (Missing Required Fields)

This is one branch ending in a "bad request" response.

{
  "status": "error",
  "message": "Missing required fields: name, breed"
}

API response: 401 Unauthorized (Invalid API Token)

This is one branch ending in an "unauthorized" response.

{
  "status": "error",
  "message": "Unauthorized. Invalid API token."
}

API response: 409 Conflict (Duplicate Microchip ID)

This is one branch ending in a "conflict" response.

{
  "status": "error",
  "message": "A pet with this microchip ID already exists."
}

Composite API: Get pet, add a pet, and order pet food

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.

API request body

  • 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 a petId.

    • Create Pet (createPet) – Creates pet details using the response from getPet.

    • 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"
      }
    }
  ]
}

Lookup: Get a pet

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.

Import: Add a pet

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.

Import: Create an order

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.

API response: Successful

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"
      }
    }
  ]
}

API response: Bad Request (Missing Required Fields)

This is one branch ending in a "bad request" response.

{
  "status": "error",
  "message": "Missing required fields: name, breed"
}

API response: 401 Unauthorized (Invalid API Token)

This is one branch ending in an "unauthorized" response.

{
  "status": "error",
  "message": "Unauthorized. Invalid API token."
}

API response: 409 Conflict (Duplicate Microchip ID)

This is one branch ending in a "conflict" response.

{
  "status": "error",
  "message": "A pet with this microchip ID already exists."
}