Passez à la construction !
Organisez vos données
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 ! :magicien:
URL ou URI ?
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 :).
Définissez les ressources
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 GEThttps://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.
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 :
Verbe HTTP | endpoint | Actions |
GET | /commands | Lister les commandes |
POST | /commands | Passer une commande |
GET | /commands/123 | Détails de la commande 123 |
PUT | /commands/123 | Modifie la commande 123 |
DELETE | /commands/123 | Annule la commande 123 |
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.
Liez les ressources entre elles
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 ?
Optimisez la recherche des données
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 ?
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 !
La réalisation de l'API !
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.:p
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.
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.
Écrire chaque fonctionnalité sous la forme d'une URL et créer les endpoints.
Coder la fonctionnalité, c'est-à-dire écrire un programme informatique permettant de réaliser la fonctionnalité.
Tester la fonctionnalité.
Voici un exemple pour vous montrer à quoi ressemble une API une fois terminée :
Règles générales dans la conception d'API
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).
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 !
Quelques conseils
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 !
Avant de la mettre en production sur le web, vous devez la tester ! C'est l'objet du dernier chapitre !
