Affichage de la liste des ressources

Maintenant que tous les prérequis sont en place, nous allons commencer à utiliser cette REST API. Le premier exemple que nous allons mettre en place est d’obtenir et d’afficher la liste des ressources dans Sciforma.

En examinant la documentation REST API fournie par Sciforma, nous pouvons trouver une section dédiée aux ressources, précisément le premier élément, qui traite de la récupération des informations sur les ressources.

Cette partie donne des informations précieuses comme :

Le type de demande

Plusieurs commandes sont utilisées lors des requêtes de l’API REST. Dans ce cas, GET est utilisé pour la lecture des données. Dans d’autres cas, nous utiliserons POST (pour la création de données) ou PATCH (pour la mise à jour des données).

La syntaxe de requête

C’est la partie spécifique de l’URL qui est ajoutée à l’URL REST de base que nous avons vue dans le chapitre précédent. Elle précise ce que l’on compte faire. Dans ce cas, il s’agit de /ressources. Get resources pour indiquer que l’on veut lire des ressources. Logique, non ?

Quelques exemples de code

Un exemple de base est décrit en plusieurs langues. Si nous nous concentrons sur le premier onglet, nous pouvons voir des choses intéressantes (même si nous n’utiliserons pas CURL). Un exemple de syntaxe claire avec l’URL de base (REST URL + commande) et plusieurs paramètres est affiché. C’est une bonne référence pour construire votre requête.

Le scope

Il vous rappelle le scope minimal qui doit être accordé pour lancer la demande et obtenir des résultats avec succès.

Comme nous l’avons vu dans le chapitre précédent, ce scope doit être :

1. Déclaré dans Sciforma dans votre External Application
2. Répété dans Postman ou dans votre code.

Les paramètres

Voici une liste des paramètres acceptés, y compris leurs types et descriptions.

Les réponses

Cette section décrit les types de réponses que votre demande peut recevoir, selon qu’elle a été acceptée ou non.

<! > Dans la vie réelle, les réponses renvoyées ne sont pas toujours celles décrites ici.

Commençons à utiliser Postman.

Revenons à notre session Postman (client léger ou lourd), configurée comme nous l’avons vu dans la partie I.

Aller à la collection et ajouter une nouvelle demande

Donnez un nom à votre demande : Liste des ressources

Le type est GET, rien à changer, mais vous pouvez remarquer que plusieurs autres valeurs seraient disponibles si nécessaire.

Comme expliqué dans le paragraphe précédent, l’URL à fournir est votre URL de base pour accéder à l’API REST ainsi que la commande spécifique, telle qu’affichée dans la documentation.

Remarquez que l’on utilise la variable {{rest_url}} au lieu de taper l’URL réelle. C’est une bonne pratique.

Passer ensuite à l’onglet Autorisation et confirmer l’utilisation de l’autorisation accordée au niveau de la collection.

Enfin, vous pouvez aller à l’onglet Header et, à côté de la variable Accept, copier-coller le contenu que vous venez de lire dans la documentation de l’exemple CURL.

Si vous ne pouvez pas changer la variable existante, vous pouvez la désélectionner et en créer une nouvelle (je ne suis pas sûr que ce soit une bonne pratique, mais ça marche).

Enregistrez votre travail et cliquez sur le bouton [Save]

Vous devriez obtenir quelque chose comme ceci :

1. un statut 200 qui indique que tout s’est bien passé
2. une collection de documents décrivant les ressources.

Le tout sous la forme d’un JSON.

Notez que si vous avez fait une erreur lors de la création de l’URL, comme, en utilisant : {{rest_url}}/resources_with_an_error, vous obtiendrez une erreur 404 :

Si vous n’incluez pas les ressources:read dans la portée, c’est une autre erreur : une erreur 401

Aller plus loin avec Postman.

Voyons quelques options supplémentaires que nous pourrions utiliser avec Postman.

Plus d’enregistrements

Si vous prêtez attention au résultat, vous n’avez que 30 enregistrements, pas la liste complète. Pour récupérer la liste entière, vous devez jouer avec deux paramètres : Limit et Offset. Offset spécifie la position à partir de laquelle Sciforma commence à renvoyer les enregistrements de ressources, et Limit indique le nombre d’éléments à retourner.

Si vous voulez afficher les enregistrements #100 à #150, vous utiliseriez la requête avec les paramètres suivants :

{{rest_url}}/resources?offset=100&limit=50

Dans le cas où l’on effectuerait cette requête depuis un script, il faudrait utiliser, pour parcourir la liste complète des ressources, une logique comme celle-ci.

# browse all resources by 'pages' of 50
limit = 50
offset = 0
repeat:
	result = get_resources(offset, limit)
	offset = offset + limit
until resilt is empty

< Ce n’est pas un langage de programmation existant, juste une façon de représenter l’algorithme. >

Davantage de données

Si vous prêtez encore attention au résultat, vous remarquerez que chaque enregistrement retourné ne comporte que 8 champs :

• ID (c’est-à-dire l’identifiant interne)
• last_name
• first_name
• organisation (chemin complet)
• statut
• start_at
• end_at
• calendar_status.

Que faire si vous voulez afficher plus de données ? Encore une fois, la section CURL dans la documentation fournit des informations précieuses sur l’utilisation de paramètre. On voit qu’il est possible de spécifier la liste des champs (fields) que l’on veut obtenir.

Supposons que vous voulez récupérer l’adresse e-mail. Vous devez modifier l’URL pour

{{rest_url}}/resources? fields=Email Address 1

Il ajoutera ceci aux enregistrements retournés

Vous pouvez ajouter de nombreux champs séparés par des virgules.

Notez que ce que nous appelons ID dans l’interface HTML est maintenant connu comme external_id.

Notez également que les champs datés (comme la disponibilité) ont un format d’exportation plus complexe.

Dans cet exemple, la disponibilité était nulle à partir du 1/1/70 (le début de l’heure de Java) jusqu’à la probable date de création au 1/12/2019. Il est revenu à zéro le 31/12/2100, marquant sa date de fin prévisionnelle (ce qui, dans ce cas-ci, signifie que la ressource serait toujours opérationnelle aujourd’hui).

C’est tout. Nous sommes désormais aptes à commencer à explorer les données et les capacités de Postman. Dans le prochain chapitre, nous allons apprendre comment mettre à jour les données, toujours en utilisant Postman.