This section will describe about how to create Api Mappings to an existing Api Function. If you don't know how to create an API Function, please refer How To Create API Function.

An API Mapping defines how API response data should be used to insert or update records in a Business Central database table (both base and extension).

To understand the API Mapping behavior, we will use a API Call to https://dummyapi.online/api/users/1 which will return a response with a fictitious user.

For example, let's assume that your API Function retrieves response with only a single result when it is executed, and you want to create a new record in the database table with that data results (api response data). The below process explains you how to achieve this.

1. Create an API Set In this case create an API Set as below.

2. Create an API Function In this case create an API Function as below.

   Here we used Static Path column value as users/1, which returns only the user whose id is 1.

3. Click on Execute action to run the selected API Function, the results are generated and available on the API Message. Click Yes to open the API Message.

4. In the API Message window you can see, how the Query Request was formed and how the Response looks like in a json format.

5. Now that we have the response data, if we want to create this response data as a Business Central table record, we need to define API Mappings for this.

6. If the Buffer Processing Type is JSON, it determines the path structure of the response data when building the data buffer.

7. After selecting the Buffer Processing Type as JSON, try to execute the API Function by clicking on the Execute action.

8. Open the API Message and select Message Data Buffer under Related action, which will show the path structure of the response data.

9. To Create API Mappings for this API Function, search for your API Function, select it and choose API Mappings.

10. On the API Mappings page, you need to define the mapping entries and as per your mappings, the API Engine maps the response data from the data buffer.

11. In this case if you want to store the response data, you need to create a table for the data storage or you can use already existing database table and provide that table and its fields on the respective columns on the API Mappings page.

12. Assume that you have a table already defined and you want to create entries on that table with the response data which you have received.

13. The below is the API Mapping screen with the required columns setup defined.

Definitions of the fields entered for this How-To:

a) Sequence - Allows a Source ID to map to more than one DB Field.

b) Successful Root Note - Indicates if this is the outer processing (table) Node of the Function for Successful API Calls.

c) Source ID - The Source ID of the mapping, should be unique for this function.

d) Source Type - The Type of Node this mapping represents (Element, TableNode, NormalizedNode, RecordNode, Record Node Value, External).

e) Parent Source ID - The Source ID of the Parent Node of this record.

f) Table No. - The Table Number that the value of this mapping should be recorded in.

g) Table Caption - The Table Caption that the value of this mapping should be recorded in.

h) Field No. - The Field Number of the Table that the value of this mapping should be recorded in.

i) Field Caption - The Field Caption of the Table that the value of this mapping should be recorded in.

j) IsKeyField - Indicates whether the field is (or one of) the PRIMARY keys to the Table No.

14. In this case the response data is mapping to the Table No. 50110 i.e CustomUsers.

15. The data buffer is having path structure of the response data, where the fields id, name, username and email are available under \RESPONSE path structure.

16. The API Engine take cares in creating the entries from the data buffer to the mapped table(s) and its fields under API Mappings.

17. After executing the API Function, in this case, the response data is available under Table CustomUsers.

18. Find the below video for this process.

    

We already seen Simple Api Mapping where we are directly mapping Json response data with the Table and its fields. But some json response data may not contain simple key and value pair combination i.e "Key": "Value", ex: "id":"101". The Json response data may contain object type keys, means a key in the json response data may contain an object type of value.

The below is a sample json response data with object type key.

{

 "id": 1,

 "name": "John Doe",

  "address":
 {

    "street": "123 Main St",

    "city": "San Francisco",

    "state": "CA",

    "zipcode": "94111"

 }

 "username": "johndoe",

 "email": "[email protected]",
}

In the above json data the key "address" is a type of object, where it is holding a set of key and value pair of entries inside that.

The below screen shows how to map the "address" object fields to a table and it's fields.

In the above mapping "address" object is the part of the root RESPONSEOBJECT and "street","city","state" and "zipcode" are part of the "address" object.

So that the "Parent Source ID" column value for "street","city","state" and "zipcode" fields is same i.e "/RESPONSEOBJECT/address".

Once executing the api function the address object fields will map to the respective mapping fields defined the API Mappings.

Sometimes we may get a Json response data which is an array response, and it is holding multiple objects inside that array.

Find the below screen for this type of Json response data.

If you notice above Api response, the response data is started with an array and inside that array, it is having multiple objects, and each object is having its own key and value pair of information inside. In this example it is holding multiple users lists.

Create a new api function and add api mappings for that api function. The below is the reference mapping screen for this.

API Function:

API Mapping:

Result: After executing the above api function, the API Engine sends a request to the endpoint, retrieves the data, stores the data in the data buffer and finally maps the data buffer data with the mappings defined.

Here is another kind of Json response data we may receive, where we have a key, which is an array, and it is holding single or multiple objects inside that array element. The below is the example for this type of json response data (Reference: https://freetestapi.com/api/v1/airlines/1).

{
"id": 1,
"name": "Lufthansa",
"code": "LH",
"country": "Germany",
"founded": "1953",
"fleet_size": "300+",
"headquarters": "Cologne, Germany",
"website": "https://www.lufthansa.com/",
"destinations": [
    {
        "name": "New York",
        "code": "JFK"
    },
    {
        "name": "London",
        "code": "LHR"
    },
    {
        "name": "Paris",
        "code": "CDG"
    }
 ]
}

In the above api response it is having destinations as a key and it is an array, and it is holding multiple destinations as objects inside.

As per the response, it is having multiple destinations for an airline. So, it required two tables, one is having airlines details, and the other table is having its destinations details. The below are the table structures.

Create an API Function to retrieve a particular airline and its destinations as below.

Define API Mappings for the above API Function as shown below.

Execute the api function, which retrieve a single airline detail and its destinations.

Create list pages for airlines and its pages to view the results. After executing the above function, you can see it's result as shown below.

In the above example where you are able to retrieve a Single airline and its destination details. Now, we can see how to retrieve a list of airlines and its destinations.(Reference: https://freetestapi.com/api/v1/airlines).

 [
  {
   "id": 1,
   "name": "Lufthansa",
   "code": "LH",
   "country": "Germany",
   "founded": "1953",
   "fleet_size": "300+",
   "headquarters": "Cologne, Germany",
   "website": "https://www.lufthansa.com/",
   "destinations": [
    {
        "name": "New York",
        "code": "JFK"
    },
    {
        "name": "London",
        "code": "LHR"
    },
    {
        "name": "Paris",
        "code": "CDG"
    }
  ]
 },
 {
  "id": 2,
  "name": "Emirates",
  "code": "EK",
  "country": "United Arab Emirates",
  "founded": "1985",
  "fleet_size": "250+",
  "headquarters": "Dubai, UAE",
  "website": "https://www.emirates.com/",
  "destinations": [
    {
        "name": "Dubai",
        "code": "DXB"
    },
    {
        "name": "New York",
        "code": "JFK"
    },
    {
        "name": "London",
        "code": "LHR"
    }
  ]
 }
]

Create an API Function for this as shown below.

Define API Mappings for the above api function as shown below.

Execute the above api function and you can get all the Airline details and their destinations as shown below.

These all are the different scenarios of API Mappings, all the steps and examples explained above will help you in defining your own as per your business needs.

I hope this helps you and solve your business needs, Thank You So Much and Good Luck. 😃