How to define the path to selecting JSON objects?

Coupler.io allows you to integrate with almost any API that returns responses in JSON format. 

In most cases when you fetch a list of some objects, JSONArray will be returned.

A JSONArray is an ordered sequence of values. 

JSONArray can be placed to a different level in the JSON response. Depending on the placement, the Path parameter should be defined in the Coupler.io settings. Let's review the most frequent cases and appropriate settings to use in Coupler.io.

To check To check the JSONArray structure that your API returns, use API documentation and an API client, such as Postman.

JSONArray on the root level

Let's check out the easiest variant in terms of setup. For example, the API response looks like this:

[
   {
      "id":"76013791",
      "customerName":"JOHN DOE",
      "total":1409.62
    }
]

Keep the  Path parameter empty in Coupler.io settings:

You will get the following result in the destination file:

JSONArray inside the JSONObject

The second most popular variant of the JSONArray structure is when the list of the needed objects is placed inside a JSONObject with 1 element:

{
   "orders":[
      {
         "id":"76013791",
         "customerName":"JOHN DOE",
         "total":1409.62
      }
   ]
}

If you leave the  Path parameter empty in Coupler.io settings, you'll get a result with the headers named in the following way: 'orders.id', 'orders.customerName', 'orders.total'. 

To get proper names of the headers in your result, use a name that was placed before :[ in the JSON response (same part in the headers names) in the Path parameter. In our example, add 'orders' as a Path parameter value:

You will get the following result in the destination file:

JSONArray inside embedded JSONObject

It is a similar case to the 'JSONArray inside the JSONObject', but the array is placed inside a few embedded objects:

{
   "results":{
      "orders":[
         {
            "id":"76013791",
            "customerName":"JOHN DOE",
            "total":1409.62
         }
      ]
   }
}

If you leave the Path parameter empty in Coupler.io settings, you'll get a result with the headers named in the following way: 

To get proper names of the headers in your result, use a combination of elements' names that were placed before  :[ in the JSON response (same part in the headers names) in the Path parameter. In our example, add 'results.orders' as a Path parameter value:

You will get the following result in the destination file:

JSONArray with embedded JSONArray

Some APIs can return a list that you need inside another list, for example, a products list inside one order element from the orders list:

{
   "results":{
      "orders":[
         {
            "id":"76013791",
            "customerName":"JOHN DOE",
            "total":1409.62,
            "products":[
               {
                  "id":"prod1",
                  "name":"T-Shirt",
                  "size":"M",
                  "quantity":"3",
                  "total":54.99
               }
            ]
         }
      ]
   }
}

If you leave the Path parameter empty in Coupler.io settings, you'll get the following result with all the data in a single row:

As you can see on the screenshot above, the number 0 was added after 'results.orders'. It is the position number of the first order in the array of orders. Same for 'results.orders.0.products' -> 0 after this string is the position of the product in the array of products. 

A JSON array is zero-terminated - the first index of the array is zero (0). Read more.

To extract an order with products, use ' results.orders' in the Path parameter:

You will get orders data in the destination file + 1 row per product that was in the order. In our example, the order data (yellow) will be duplicated. 

Note: on the image below, the second product 'prod2' was added for better visibility; it was not originally placed in the JSON above.

To only extract products data for a particular order (the first one since we only have one in the example JSON), use ' results.orders.0.products' in the Path parameter:

Note: For the first element in the array, the position number (index) will be 0; for the second one - 1, and so on.

Data for products only will be saved to destination file:

In case you faced issues with defining the Path parameter value, do not hesitate to contact our Support Team: contact@coupler.io.