Introduction aux API Web

Le terme "API", tout comme le terme "cloud", est souvent utilisé dans les conversations techniques informelles. Si le terme vous est familier, mais que vous ne savez pas exactement comment fonctionnent les interfaces de programmation d'applications (API), ce article est fait pour vous.

J'ai d'ailleurs abordé ce sujet à plusieurs reprises sur mon blog et notamment dans un exemple de l'utilisation de l'API REST pour Hadoop.

Enfin, si vous vous intéressez à l'API Rest pour SAS Viya (Grâce aux API REST de SAS, vous pouvez créer et accéder aux ressources SAS en utilisant n'importe quelle technologie client), cet article peut vous apportez des précisions sur le fonctionnement des API.

Dans cette article je tente d'aborder l'essentiel de cette pièce maîtresse du développement Web moderne, expliquant ce que sont les API et comment les utiliser pour intégrer rapidement des données dans vos sites Web.

Pour faire simple, cet article est une introduction de niveau débutant aux API, mais il ne s'agit pas d'une introduction au développement Web. Pour tirer le meilleur cet article, vous devez donc être à l'aise avec les technologies de base du développement Web. Vous n'avez certainement pas besoin d'être un expert, mais vous devriez avoir de l'expérience dans la création de vos propres sites Web simples.

L'objectif de cet article est de vous fournir une introduction aux API afin que vous compreniez mieux ce qu'elles sont et me concentrer sur la manière de les utiliser et, je l'espère, sur la manière la plus simple et la plus directe de les utiliser. Je vais donc ignorer de vous présenter certains termes courants comme REST, CORS et SOP. Vous n'avez pas besoin de les comprendre pour ce cour. Lorsque vous entendez ou lisez des articles sur les API, vous verrez presque toujours le terme REST associé. Il s'agit simplement d'une norme pour les API, et aujourd'hui, presque toutes les API sont conformes à la norme REST. CORS et SOP sont des protocoles principalement destinés à assurer une certaine sécurité aux API. Mais lorsque vous débutez avec les API, le fait de se concentrer sur ces protocoles peut compliquer inutilement les choses, et nous pourrions très bien nous débrouiller sans nous en préoccuper maintenant.

Qu'est-ce qu'une API ?

On va commencer par le début. API signifie Application Programming Interface. Bien que la signification de cette expression ne soit pas toujours évidente au premier abord, il s'agit en fait d'un concept assez simple. En gros, il s'agit d'un intermédiaire logiciel qui permet à deux applications de communiquer entre elles. Par exemple, chaque fois que vous utilisez une application comme Facebook, envoyez un message instantané ou consultez la météo sur votre téléphone, vous utilisez une API.

Vous l'avez donc compris, il existe toutes sortes d'entreprises ou d'organisation qui fournissent des données par le biais de leurs API.

Par exemple le COVID Tracking Project collecte, recoupe et publie les données COVID-19 des 56 États et territoires américains dans trois domaines principaux : dépistage, hospitalisation et résultats des patients… Ces données sont accessibles au format json.

Les entreprises fournissent une documentation qui explique quelles données sont disponibles et comment demander et obtenir ces données. Puis, comme le serveur d'un restaurant, vous demandez ces données à l'API, qui va les chercher et vous les ramène pour que vous puissiez les utiliser comme bon vous semble. Vous n'avez pas à créer les données vous-même. Vous n'avez pas à créer un outil pour y accéder. Et vous n'avez pas besoin de comprendre comment c'est fait.

Comma au restaurant, il vous suffit de commander et de déguster.

• Vous n'avez pas à créer les données vous-même.
• Vous n'avez pas à créer un outil pour y accéder.
• Vous n'avez pas besoin de comprendre comment c'est fait.

Comme au restaurant, il suffit de commander et de déguster.

Request et response

Afin de comprendre les API, il est important d'avoir une compréhension de base du cycle de demande et de réponse. Avec la demande, vous demandez quelque chose. Et avec la réponse, vous recevez quelque chose en retour. Le cycle de demande et de réponse implique une communication entre vous, et par vous j'entends votre navigateur Web, et un serveur quelque part.

Vous et votre navigateur Web êtes souvent appelés le client. La requête que vous faites généralement est une requête GET. Vous faites une demande pour obtenir des données du serveur. Et c'est sur ce point que nous allons nous concentrer dans cet article. Faire des requêtes GET pour obtenir des données d'une API.

GET n'est qu'une des choses que nous pouvons demander au serveur dans notre requête. Il existe un certain nombre d'options de requête utilisant le protocole HTTP. GET est l'un des plus courants, et c'est celui que nous allons utiliser.

Donc, après avoir envoyé une requête GET au serveur, ce dernier vous renvoie une réponse. Si vous avez été sages et que vous avez fait une demande correctement, cette réponse comprendra toutes les données que nous espérions obtenir de l'API.

Elle est pas belle la vie ?

JSON

En faisant une requête Get, votre objectif est de recevoir des données en réponse. Quelles données allez-vous recevoir ? En fait, la vrai question est : dans quel format seront ces données ?

Il existe deux principaux formats de données. XML et JSON. XML était le format le plus populaire, mais aujourd'hui JSON domine définitivement le web.

• 

C'est le format de données avec lequel vous allez travailler. JSON est l'abréviation de JavaScript Object Notation. JSON formate les données comme un objet en JavaScript, de sorte qu'il peut être facilement utilisé dans des projets Web, comme n'importe quel autre objet JavaScript. Ce qui surtout cool avec JSON, c'est qu'il est composé de paires clé-valeur. La clé est comme une propriété, et ensuite la valeur correspondante.

Parser la réponse

Lorsque des données sont envoyées dans la réponse, elles sont envoyées sous forme de chaîne de caractères, ou de texte. Afin de travailler avec les données, nous voulons les convertir en un objet

Vous pouvez examiner un exemple de nos données dans leur forme brute, sous forme de chaîne, puis sous forme d'objet après leur analyse. Vous pouvez utiliser une extension Chrome appelée JSON Formatter qui vous permet de basculer facilement entre le JSON brut et le JSON analysé pour voir la différence. Je vous conseille vivement d'installer et d'utiliser cette extension gratuite. Il en existe d'autres qui font à peu près la même chose, alors n'hésitez pas à utiliser l'extension de votre choix.

La documentation

Le point de départ pour travailler avec une API est sa documentation. Une bonne API doit disposer d'une documentation détaillée expliquant comment l'utiliser.

La documentation doit décrire les principes de base de l'API, le type de données que vous pouvez obtenir. Elle doit expliquer les conditions d'utilisation de l'API, si elle est gratuite ou payante, si il faut s'enregistrer et obtenir une clé.

La documentation doit également fournir des exemples de requêtes et de réponses renvoyées et, plus important encore, pour travailler réellement avec l'API, il doit vous fournir des points d'accès et des paramètres.

Les points de terminaison vous indiquent les différents endroits où vous pouvez vous connecter à l'API. Il s'agit d'URL et la fin de chaque URL vous connecte à des options de données spécifiques de l'API.

Avec SAS VIYA, par exemple, la documentation explique explique comment enregistrer des clients, créer des jetons d'accès et effectuer des appels d'API de base. Vous trouverez également dans cette documentation des directives sur les collections, les liens, la pagination, le filtrage et d'autres informations générales sur l'utilisation des API REST de SAS Viya.

Des exemples d'utilisation sont disponible sur le github SAS REST API Examples - SAS Viya Preview Il s'agit d'un dépôt de repository git contenant des exemples montrant les capacités des API REST de SAS. Vous pouvez utiliser ces exemples pour apprendre ou pour valider votre environnement.

Les codes retours

Parlons brièvement de ces codes retours. On va dire que si vous construisez bien vos requêtes vers les API, que vous êtes bien authentifié et que tout fonctionne sur le serveur, vous obtiendrez un code retour 200.

Mais, il est bon de creuser un peu plus profondément et de voir quelles autres informations sont à notre disposition afin de mieux gérer les erreurs éventuelles.

Une partie de la réponse que nous ne voyons généralement pas, ou à laquelle nous ne prêtons pas beaucoup d'attention, est constituée de codes qui nous renseignent sur le statut de notre demande.

L'un d'entre eux, je suis prêt à le parier, vous est déjà familier de manière frustrante : L'ennuyeuse erreur 404, page non trouvée. I

l existe quatre groupes de codes d'état. Dans chaque groupe, il y a des chiffres spécifiques qui nous donnent plus de détails sur la réponse, mais il suffit généralement de connaître les quatre groupes généraux.

Comme je le disais au début de ce chapitre, Les codes d'état dans les 200 nous disent que tout était correct et nous indiquent que la demande a été reçue et que la réponse a été envoyée sans problème.

Les codes d'état 300 nous indiquent que nous avons été redirigés vers la ressource appropriée.

Les codes d'état 400 sont probablement les autres codes courants que nous sommes susceptibles de voir. Ils nous indiquent qu'il y a eu un problème de notre côté. Quelque chose ne va pas avec notre requête. En général, lorsqu'on travaille avec des API, cela signifie qu'il y a un problème avec l'URL de la demande.

Enfin, les codes d'état 500 nous indiquent que quelque chose ne va pas du côté des serveurs.

Pour résumer :

2XX	Requête traitée avec succès
401	Accès non autorisé
403	Accès interdit (L'utilisateur de l'API n'a pas la permission d'effectuer cette requête)
400	Mauvaises données d'entrée (exemple : le format de certains paramètres n'est pas respecté)
404	L'objet demandé est introuvable
500	Erreur interne du serveur

Je peux schématiser le fonctionnement en vous présentant le schéma ci-dessous :

Si vous souhaitez en savoir plus je vous invite à visiter la page Choosing an HTTP Status Code — Stop Making It Hard du site codetinkerer.

Et avec SAS VIYA ?

La première question que l'on peut se poser est : où les apis sont-elles utilisées dans SAS Viya ?

La réponse est simple. Un peu partout 😀

• Dans toutes les interfaces visuelles de SAS Viya
• Dans SAS Worflow Manager
• A travers les API des commandes SAS Viya
• Avec SAS CAS Server
• Avec SAS Micro Analytic Service
• Avec SAS ESP
• ...

Ok, c'est bien joli Nicolas, mais que peut-on faire avec les API REST de SAS ?

J'ai envie de vous répondre qu'il est possible de faire à peu près tout ce que l'on souhaite, mais, pas exemple il est possible de :

• Exécuter des jobs SAS Viya
• Construire un système d'alerte
• Automatiser ses processus CI/CD
• Collecter des informations de sécurité
• ....

Le plus simple est de vous proposer un exemple avec CAS, non ?

Un exemple avec CAS

SAS publie deux ensembles d'API: SAS Viya REST APIs et
Cloud Analytics Service (CAS) REST APIs

Cloud Analytics Service (CAS) REST permet aux utilisateurs d'accéder aux données et aux procédures SAS et de les intégrer dans leurs applications.

Comme vous vous en doutez, je pars de la documentation pour obtenir des informations sur la manière de construire et d'utiliser l'API. Comme toutes les api Web, l'API CAS peut soumettre des actions et renvoyer les résultats. Les paramètres et les données de résultat sont au format JSON.

Pour spécifier vos paramètres, encapsulez les attributs dans un objet JSON, puis soumettez une méthode POST sur l'action.

L'URL de votre action comprendra l'UUID de votre session au format : /cas/sessions/{uuid}/actions/{action}.

Créer une session

La première étape consiste à créer une session. J'utilise la commande cURL suivante pour créer la session.

La réponse est un objet JSON avec un ID de session :

C'est cet ID session qui permet de construire les URLs pour le reste des appels REST.

Construire l'appel de l'API REST CAS

Pour allons maintenant fetcher une table. J'utilise un fichier json (tablefetch.json) contenant les informations que je sois préciser pour récupérer le contenu de cette table :

Les parametres utilisable sont indiqué dans la documentation SAS Viya System Programming Guide - Tables Action Set: Syntax

Je peux ensuite exécuter la commande curl ci-dessous pour fetcher ma table :

Conclusion

Merci beaucoup d'avoir lu cette article d'introduction aux API Web. J'espère que vous avez une meilleure compréhension de ce que sont les API et de la façon dont vous pouvez les utiliser dans vos propres applications.

Je vous encourage vraiment à jouer avec de plus en plus d'API. Plus vous travaillez avec elles, plus vous vous sentirez à l'aise avec elles.

Il existe des tonnes d'API publiques gratuites et amusantes. Rapid API est une excellente ressource. Et si vous effectuez une simple recherche Google sur les API gratuites, vous trouverez également de nombreuses autres ressources intéressantes.

Pour aller plus loin

• OpenID Connect Opens the Door to SAS Viya APIs
• Authentication to SAS Viya: a couple of approaches
• Building custom apps on top of SAS Viya
• SAS REST API Examples - SAS Viya Preview
• Documentation officielle: https://developer.sas.com/apis/rest/
• Exemples: https://github.com/sassoftware/devsascom-rest-api-samples

Code source de différents projets : 

• sasctl: https://github.com/sassoftware/python-sasctl
• pyviyatools: https://github.com/sassoftware/pyviyatools
• viyaRestPy: https://github.com/xavierBizoux/viyaRestPy
• restaf: https://github.com/sassoftware/restaf