wikinotes

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.
{{tag>dev api rest}}

Notes et transcriptions du cours [[https://openclassrooms.com/fr/courses/6031886-debutez-avec-les-api-rest|Débutez avec les API REST]] proposé par **esri France** disponible sur la plateforme [[https://openclassrooms.com|Openclassrooms]].


===== Construire son API =====

===== Organisez vos données =====

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.

===== URL ou URI ? =====

Ces deux termes sont des notions informatiques qui prêtent souvent à confusion. En effet, **URI** est l'abréviation de **U**niform **R**essource **I**dentifier, 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 **U**niform **R**essource **L**ocator. 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.

===== 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 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 :

^ 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 ?

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.


===== 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 ?

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 !

===== 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.

  - 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é.

===== 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). 

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 !


===== 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 !


[[310_conception_api|◁ Précédent]] | [[000_start|⌂ Retour au sommaire]] | [[330_tester_api|Suivant ▷]]
wikinotes

Outils pour utilisateurs

Outils du site

Outils de la page
