wikinotes

Vous devez dans un premier temps organiser vos données utilisées par votre future API.

En effet, les fonctions mises à disposition par votre API en dépendront grandement. Par exemple, si votre API doit gérer les livres d'une bibliothèque nationale, les fonctions à réaliser dans l'API seront différentes que s'il s'agit de la gestion des livres d'une petite structure. Mais vous l'aurez compris, il est aussi intéressant de penser à l'évolutivité de l'API. Si votre API répond aussi bien aux besoins d'une bibliothèque nationale que d'une petite structure, vous aurez tout compris aux API !

Le choix d'une API REST vous laissera plus de liberté dans vos décisions de conception.

Ces deux termes sont des notions informatiques qui prêtent souvent à confusion. En effet, URI est l'abréviation de Uniform Ressource Identifier, ce qui signifie identifiant de ressource uniforme.

Une URL est une information permettant de localiser un élément. Il s'agit de l'abréviation de Uniform Ressource Locator. L'adresse d'un site Internet est une URL, par exemple :).

Par analogie, l'URI correspond à l'identité d'une personne alors que l'URL correspond à une adresse postale.

Toutes les URL sont des URI, car il est par exemple possible d'identifier une personne avec son adresse, mais toutes les URI ne sont pas des URL. Le nom d'une personne ne donne aucune information sur sa localisation.

C'est quoi, déjà, une ressource ? Prenez l'exemple du restaurant VGBurger : le burger est une ressource, la carte de menu est une ressource. Vous assignez ensuite une URL à chaque ressource.

Par exemple, l'URL GET https://myvgburger.com/commands peut renvoyer la liste des commandes en cours. Tandis que cette URL, GET https://myvgburger.com/commands/<id_commande>, renverra une ressource particulière, en l’occurrence une commande spécifique.

La chaîne “commands/<id_command>” constitue le endpoint (point terminal) supporté par votre API. Pour faire simple, c'est la seule manière d'accéder à une fonctionnalité précise.

Et c'est important, un endpoint ?

Bien sûr ! Les endpoints jouent un rôle clé dans la garantie du bon logiciel, car ils spécifient où les API peuvent accéder aux ressources !

Votre API de gestion d'une bibliothèque pourrait ressembler à ceci :

Chaque ressource peut être accessible en HTML ou en JSON.

Vous allez maintenant déterminer quelles données vont être échangées entre le client et le serveur.

Votre API est presque complète ! Vous voyez ce qu'il manque ?

Un endpoint sur la ressource consommateur ! En effet, /customers/<id> peut être le endpoint d'accès à la ressource du consommateur de VGBurger !

Maintenant, il faut les associer aux commandes ! Quel endpoint allez-vous mettre en place ?

Une réponse : POST Https://vbburger.com/customers/<id>/commands/<id_command>. Par exemple, le endpoint /customers/3/commands/5 renvoie la commande 5 du client 3.

Au fil du temps, les données vont accroître et les endpoints listant les ressources ne seront peut-être plus adaptés. Par exemple, parmi les millions de vgburgers vendus, si vous avez recherché combien d'entre eux étaient avec de la mozarella, le endpoint /commands n'aurait guère pu vous aider, surtout s'il renvoie des millions d'enregistrements ! La solution ?

L'utilisation de paramètres dans l'URL, comme décrit dans la section Paramétrez votre URL pour transmettre les paramètres du chapitre Transmettez de l'information avec JSON de ce cours.

Ainsi, pour rechercher les vgburgers avec de la mozarella, l'URL serait la suivante : http://vgburger.com/commands?fromage=mozarella.

Autre exemple, vous souhaitez tous les vgburgers avec de la mozarella et un pain aux céréales ; l'URL pourrait être la suivante : http://vgburger.com/commands?fromage=mozarella&pain=cereale

Vous avez maintenant tous les éléments pour construire votre API. Enjoy !

Maintenant que vous avez tous les outils pour construire une API, voici les étapes de sa réalisation pour un site web pour un restaurant VGBurger, qui fait de la vente en ligne de burgers végétariens.

1. Analyser le cahier des charges, c'est-à-dire analyser et comprendre le besoin. Par exemple, VGBurger veut vendre des burgers végétariens à la carte, c'est-à-dire que le client a le choix parmi 10 ingrédients.
2. Traduire le besoin sous forme de fonctionnalité. Dans l'exemple, il faudra au minimum les fonctionnalités de gestion de commandes, menu ou simple VGBurger, gestion d'ingrédients composant le VGBurger, etc.
3. Écrire chaque fonctionnalité sous la forme d'une URL et créer les endpoints.
4. Coder la fonctionnalité, c'est-à-dire écrire un programme informatique permettant de réaliser la fonctionnalité.
5. Tester la fonctionnalité.

Une API, c'est une syntaxe de verbes (GET, POST, PUT, DELETE) et de noms (arguments de l'action) pour accéder à des ressources.

Une bonne pratique est de toujours générer une variable d'état lors de l'exécution d'une action, que le résultat soit un succès ou une erreur. Dans le cas d'une erreur, il est conseillé de décrire précisément le problème et sans ambiguïté.

Par exemple, vous exécutez l'URL GET http://vgburger.com/commands?fromage=brie, le résultat sera un code 2xx (succès de la requête, qu'elle renvoie ou non des ressources).

Par contre, si vous exécutez l'URL GET http://vbburger.com/com?fromage=brie, le résultat est un code 4xx, car le endpoint /com n'existe pas.

En résumé, le résultat de chaque endpoint doit être géré, qu'il soit un succès ou un échec. De ce point dépendra la qualité de votre API !

• Une API est pour un client. Elle doit proposer des fonctions simples et évolutives.
• L'API doit être sécurisée (basique, clé d'API, OAuth).
• Préférez les noms concrets pour décrire vos ressources, évitez les verbes !
• Utilisez des minuscules pour le nommage des endpoints.
• L'API doit être documentée et illustrée par des exemples.

Vous avez maintenant tous les éléments pour construire votre API, bravo !

◁ Précédent | ⌂ Retour au sommaire | Suivant ▷