Include

Include is a parameter that can be added to filter and shape the responses of API calls. There are two main use cases:

1) One such use is for Relation Lists, where if the JSON response to an API call contains a field that references the primary index of another data entity, its record data can be included as a nested JSON object. These are not all expanded and included by default, especially not in many-records list views, in order to accelerate the API's response times and reduce load on database services.

2) Another use is to include On Demand fields, which are additional information in the same record that is omitted by default to accelerate API responses and reduce the load on database services. Some On Demand fields are based on algorithms to calculate/format the data in ways that are much heavier than basic database data fetching.

On Demand Fields

When using the API's procedurally generated technical specifications documentation, you will often see a description of an endpoint's fields list that has the text "On Demand". This means that the field is not included by default in the response payload of calls to that endpoint. As described in the introduction, this helps keep the most basic and common of API calls to a resource consumption minimum. 

One example is the "age" field of Employee data of the /employees endpoint. From the technical spec we see that it is an On Demand field:

This means that when making API calls to Employee data like:

[GET] /rest/v1/employees

The "age" field will not be included in the response. But you can add it to the response by including it like this:

[GET] /rest/v1/employees?include=age

Relation Lists

TrackTik's API has a design pattern of including the names of other data entities and their primary index number as an integer when they are a 1:1 match to the main entity's data being requested. This empowers you to "include" additional data belonging to the matched data entity in a relational way.

E.g.

Let's say you're requesting information on a client site who's ID is the integer/index 600:

[GET] /rest/v1/clients/600

Response:

{
  "company": "Fancy Mae Main Building 1",
  "customId": "FMB-01",
  "type": "SERVICE_LOCATION",
=>"region": 5,
  "id": 600
  …
}

In that response you'll notice there's a field called "region". This refers to the entity/endpoint /regions. 

If you would like to INCLUDE this region's information in the same way as if you had made a second call...

[GET] /rest/v1/regions/5

...you can by adding the parameter "include=region" to the original API call for client site data like this:

[GET] /rest/v1/clients/600?include=region

Response:

{
  "company": "Fancy Mae Main Building 1",
  "customId": "600",
  "type": "SERVICE_LOCATION",
  "id": 600,
=>"region": {
     "customId": "SE-1",
     "name": "South Eastern",
     "company": "ACME Security",
     "parentRegion": 2,
     "status": "ACTIVE",
     "id": 5
   }
}

Notice what used to a key value pair of region : 5, is now a populated additional JSON object. 

NB: Sometimes an entity will permit the inclusion of an array of values as a 1:many, and these will require that a single entity record is being requested by specifying its index number in the request, like /clients/600 . Most relation lists will not allowed to be included in list view, where you list many records of a data entity, like if you called /clients alone without index number. This is to protect the API's response times and database services. 

Fields

The TrackTik API will provide you with valuable information in responses to API calls, and On Demand fields and Includes can enrich them even more, but for integrations where less is needed, you can choose which fields to include in responses as a list in the API call itself.

Imagine you want to call for some names of Employee data, nothing else, and it's enough to retrieve the concatenated "First Name Last Name" field known as "name", which means you don't need the breakdown of first and last names as separate fields. You can use the "fields" parameter to achieve this.

E.g.

[GET] /rest/v1/employees?fields=name

{
  "name": "Charlie Best"
},
{
  "name": "Randa Smartly"
},
{
  "name": "Palvasha Brilliant"
},
{
  "name": "Hendel Handily"
},
etc.

You can include a list of fields separated by commas and they will all be included:

[GET] /rest/v1/employees?fields=name,id

{
  "name": "Charlie Best",
  "id" : 1
},
{
  "name": "Randa Smartly",
  "id" : 2
},
{
  "name": "Palvasha Brilliant",
  "id" : 3
},
{
  "name": "Hendel Handily",
  "id" : 4
},
etc.