Inclure

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

1) L'une de ces utilisations concerne les listes de relations: si la réponse JSON à un appel API contient un champ qui fait référence à l'index primaire d'une autre entité de données, ses données peuvent être incluses en tant qu'objet JSON imbriqué. Elles ne sont pas toutes développées et incluses par défaut, en particulier dans les vues en liste avec de nombreux enregistrements, afin d'accélérer les temps de réponse de l'API et de réduire la charge sur les services de base de données.

2) Une autre utilisation consiste à inclure des champs à la demande, c'est-à-dire de l'information supplémentaire dans le même inscription qui sont omises par défaut afin d'accélérer les réponses de l'API et de réduire la charge sur les services de base de données. Certains champs à la demande sont basés sur des algorithmes qui calculent/formatent les données d'une manière beaucoup plus lourde que la collection direct de données dans une base de données.

Champs à la demande

Lorsque vous utilisez la documentation sur les spécifications techniques de l'API générée de manière procédurale, vous verrez souvent une description de la liste des champs d'un point de terminaison avec le texte "On Demand". Cela signifie que le champ n'est pas inclus par défaut dans le contenu de la réponse des appels à ce point de terminaison. Comme indiqué dans l'introduction, cela permet de réduire au minimum la consommation de ressources pour les appels d'API les plus basiques et les plus courants. 

Un exemple est le champ "age" des données sur les employés du point de terminaison /employees. Les spécifications techniques indiquent qu'il s'agit d'un champ à la demande :

Cela signifie que lorsque l'on fait des appels à l'API pour obtenir des données sur les employés, comme par exemple :

[GET] /rest/v1/employees

Le champ "age" ne sera pas inclus dans la réponse. Mais vous pouvez l'ajouter à la réponse en l'incluant comme suit :

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

Listes de relations

L'API de TrackTik a pour modèle de conception l'inclusion des noms d'autres entités de données et leur numéro d'index primaire lorsqu'ils correspondent 1:1 aux données de l'entité principale demandée. Cela vous permet d'inclure "" des données supplémentaires appartenant à l'entité de données correspondante d'une manière relationnelle.

Par exemple

Supposons que vous demandiez de l'information sur un site client dont l'identifiant est l'entier/index 600 :

[GET] /rest/v1/clients/600

Réponse :

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

Dans cette réponse, vous remarquerez qu'il y a un champ appelé "region". Il s'agit de l'entité/point de terminaison /regions. 

Si vous souhaitez INCLURE l'information de cette région de la même manière que si vous aviez effectué un deuxième appel...

[GET] /rest/v1/regions/5

...vous pouvez ajouter le paramètre "include=region" à l'appel API original pour les données du site de client, comme suit :

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

Réponse :

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

Remarquez que ce qui était une paire clé/valeur de région : 5, est maintenant un objet JSON supplémentaire rempli. 

NB : Il peut arrivé qu'une entité permette l'inclusion d'un tableau de valeurs en tant que 1:many, ce qui nécessite qu'une seule inscription d'entité soit demandé en spécifiant son numéro d'index dans la demande, comme /clients/600 . La plupart des listes de relations ne pourront pas être incluses dans la vue en liste, où vous listez de nombreux enregistrements d'une entité de données, comme si vous appeliez /clients seul sans numéro d'index. Il s'agit de protéger les temps de réponse de l'API et les services de la base de données. 

Champs

L'API TrackTik vous fournira de l'information précieuse dans les réponses aux appels API, et les champs à la demande et les inclusions peuvent les enrichir encore plus. Mais pour les intégrations où moins d'information est nécessaire, vous pouvez choisir les champs à inclure dans les réponses des appels à l'API.

Imaginez que vous souhaitiez demander quelques noms d'employés, rien d'autre, et qu'il suffise d'extraire le champ concaténé "Prénom Nom" appelé "name", ce qui signifie que vous n'avez pas besoin de la décomposition des prénoms et des noms en champs distincts. Pour ce faire, vous pouvez utiliser le paramètre "fields".

Par exemple

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

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

Vous pouvez inclure une liste de champs séparés par des virgules et ils seront tous retournés (que les champs de la liste) :

[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.