Maintenant que vous disposez d’un jeton d’accès nous allons voir comment récupérer une liste d’objet. Par exemple la liste des ressources humaines « employees ».

Requête

Exemple:

Si vous testez l’API à partir d’un compte “Essai Gratuit” :

Exemple:

Remarque

Il faut utiliser la méthode « GET ».

Réponse

1. {


2. • "queryUid": "9edbf7bcddfbd0f0db649b6da8680d61",


3. • "offset": 0,


4. • "limit": 100,


5. • "total": 250,


6. • "data": [...],


7. • "@odata.nextLink": "https://trial.nicoka.com/api//employees/?queryUi=9edbf7bcddfbd0f0db649b6da8680d61&queryPage=2"
   
   
   
   


8. }

Analyse de la réponse :

Pagination

Lorsque que le résultat de la requête (total) est supérieur à la taille de votre buffer (limit), vous pouvez récupérer les pages suivantes en utilisant les paramètres suivants :

Exemple de réponse :

1. 
   {
   


2. • "queryUid": "9edbf7bcddfbd0f0db649b6da8680d61",


3. • "offset": 10,


4. • "limit": 10,


5. • "page": 2,


6. • "pages": 3,


7. • "total": 250,


8. • "data": [...],


9. }

Taille de buffer

Vous pouvez définir la taille du « buffer » en ajoutant le paramètre « limit » dans votre requête :

Remarque

La taille maximum du buffer est de 200 enregistrements par requête pour des raisons de performance. Vous ne pouvez pas faire plus de 4 requêtes par secondes.

Trie

Vous pouvez trier les résultats de requête en ajoutant le paramètre suivant :

• Name of the field: Il s’agit du nom d’un champ existant dans l’objet que vous souhaitez. Vous pouvez aussi effectuer un trie sur des objets liés ou sous l’objet de l’objet principale dans ce cas vous devez utiliser la structure suivante :

Si vous devez effectuer un trie sur plusieurs colonnes à la fois, il vous suffit de séparer les champs avec une virgule dans le requête :

• Sort direction: ASC pour croissant et DESC pour décroissant. Par défaut les tries sont toujours croissant, il n’est donc pas nécessaire de le spécifier dans la requête :

Voici un exemple de requête avec un trie décroissant sur la date de dernière mise à jour :

Sélection restreinte à certains champs

Par défaut lorsque que vous faites un appel à l’API, le système vous retourne l’ensemble des champs auxquels vous avez accès, si vous souhaitez faire une sélection restreinte il suffit de passer vos champs dans le paramètre « $select »:

Voici un exemple de requête avec un trie décroissant sur la date de dernière mise à jour :

Vous pouvez aussi passer l’identifiant unique des champs __.

Format de sortie

L’API de Nicoka vous permet de récupérer vos données sous différents format :

• xml : il faut ajouter le paramètre __format=xml


• odata : il faut ajouter le paramètre __format=odata

Filtres

Si vous souhaitez filtrer les résultats d’une recherche il suffit d’ajouter les « champs » sur lesquels vous souhaitez filtrer dans votre requête.

Remarque

pour passer plusieurs valeurs pour un champ il suffit d’utiliser les crochets

{name_of_the_field}[]={value1}&{name_of_the_field}[]={value2}&…

Champs de type texte

Sur les champs de type “texte” Nicoka fait par défaut une recherche « commence par », si vous souhaitez faire une recherche de type « contient le mot » vous devez ajouter des pourcentages (%) autour de votre mot :

Si vous souhaitez faire une recherche stricte sur un mot il faut ajouter des apostrophes « ‘ » autour du mot :

Champ de type date

Si vous souhaitez filtrer sur un champ de type il faut passer la date au format « YYYY-MMDD » (ex 2018-12-31), si vous souhaitez ajouter une heure le format devient « YYYY-MMDD hh:mm:ss » (ex 2018-01-31 22:45:00). Le système est capable de reconnaitre d’autre type de format mais il est préférable d’utiliser celui-ci.

Par défaut lorsque vous passez une date Nicoka va effectuer un filtre « supérieur ou égale à cette date », si vous souhaitez filtrer sur une journée ou une période vous devez ajouter la date de fin à votre paramètre séparer par une virgule :

Remarque

Pour faire un filtre inférieure à une date il suffit de laisser le premier paramètre vide et la virgule

Champ type liste déroulante

Pour les recherches sur les champs de type liste déroulante vous pouvez passer l’id système du champ ou bien son libellé.

Champ type Montant ou Quantité

Pour les recherches sur les champs de type montant ou quantité le paramètre doit être un chiffre sans séparateur de millier et avec un point comme séparateur de décimales si besoin. Si vous souhaitez faire un filtre en utilisant des opérateurs comme « plus grand que » ou « plus petit que », il suffit d’ajouter l’opérateur juste avant le chiffre :

Certaines entités autorisent une recherche par mots clés, dans ce cas vous devez utiliser le paramètre « term » :

La recherche fonctionne comme dans l’application, à savoir :

• Si vous séparer vos mots clés par des espaces, le système fera une recherche « inclusive » et ne retournera que les enregistrements qui contiennent tous vos mots clés. En terme de performance il vaut mieux commencer par les mots les plus discriminants (ex : projet chef sera plus rapide que chef de projet)


• Si vous séparer vos mots par des virgules, le système fera une recherche de type « ou »


• Si vous ajoutez des apostrophes autour de vos mots clés il fera une recherche stricte sinon par défaut il fait une recherche approximative