Publié le 29 septembre 2022 par Andrew Owen
(8 minutes)
Les API (interfaces de programmation d’applications) REST (representational state transfer) existent depuis le début du siècle, lorsqu’elles ont été définies par Roy Fielding dans sa thèse de doctorat. Depuis, elles sont devenues la principale méthode de connexion des composants dans les architectures microservices.
Les API web permettent notamment à une application client d’interagir avec un service fonctionnant sur un serveur. Contrairement aux solutions antérieures telles que SOAP et XML-RPC, REST offre aux développeurs beaucoup plus de flexibilité. Par exemple, vous pouvez utiliser le langage ou le format de données de votre choix. Bien qu’en pratique, JavaScript et JSON soient souvent les choix préférés.
Les objectifs de REST sont les suivants
Des composants portables et modifiables.
Une évolutivité maximale.
La performance des interactions.
Fiabilité (la défaillance d’un composant ne doit pas entraîner l’effondrement de l’ensemble du système).
Interfaces utilisateur simples.
des communications visibles.
Il repose sur six principes de conception:
Cacheabilité. Pour l’évolutivité côté serveur et les performances côté client, les réponses doivent être définies comme pouvant être mises en cache ou non. Le cache peut être stocké dans un réseau de diffusion de contenu (CDN). L’objectif est de réduire le nombre d’interactions client-serveur.
Code à la demande (optionnel). Les réponses peuvent contenir du code exécutable (typiquement JavaScript). Cela permet au serveur d’étendre les fonctionnalités du client.
Découplage client-serveur. Le client ne peut interagir avec le serveur qu’à l’aide d’un identifiant de ressource uniforme (URI). Le serveur ne peut interagir avec le client qu’en répondant à la demande par HTTP. Il est ainsi possible de remplacer complètement l’application client sans modifier le serveur.
Architecture de système en couches. Peu importe que le client soit connecté directement au serveur ou qu’il passe par un intermédiaire. Cela permet d’équilibrer la charge et d’utiliser une couche de sécurité, séparant la logique commerciale de la logique de sécurité.
Absence d’état. Aucune information de session n’est requise ou conservée par le serveur. Cette absence de sessions serveur permet un traitement rapide de gros volumes de données.
Interface uniforme. Les ressources sont identifiées par un URI. Le client manipule une représentation de la ressource, y compris les métadonnées. Les messages décrivent eux-mêmes la manière dont ils doivent être traités. Le client découvre dynamiquement les ressources à partir de l’URI d’origine, sans qu’il soit nécessaire de les coder en dur.
Vous pouvez rencontrer des API décrites comme RESTful qui ne répondent pas à ces critères. C’est souvent le résultat d’un codage ascendant, alors qu’une conception descendante aurait dû être utilisée. Un autre point à surveiller est l’absence de schéma. Il existe des alternatives, mais OpenAPI est un choix courant avec un bon support d’outils. Si vous n’avez pas de schéma, vous pouvez en créer un en constituant une collection Postman.
En règle générale, les API REST n’utilisent que les quatre méthodes HTTP les plus courantes:
Méthode
CRUD
Code de réponse typique
POST
Create (créer)
201 Créé
GET
Read (lire)
200 Succès
PUT
Update (mise à jour)
202 Accepté
DELETE
Delete (supprimer)
204 Pas de contenu
Pour référence, l’ensemble des méthodes HTTP est le suivant:
DELETE - Supprime la ressource spécifiée.
GET - Demande des données à partir d’une ressource spécifiée.
HEAD - Presque identique à GET, mais sans le corps de la réponse.
OPTIONS - Décrit les options de communication pour la ressource cible.
PATCH - Applique des modifications partielles à une ressource.
POST - Envoi de données à un serveur pour créer une ressource.
PUT - Envoi de données à un serveur pour créer ou mettre à jour une ressource.
Vous pouvez appeler une API REST à partir de la ligne de commande en utilisant curl. Par exemple:
Avec l’autorisation de base, vous transmettez une chaîne nom d’utilisateur:mot de passe encodée en Base64. Il s’agit généralement d’une adresse électronique et d’un jeton d’authentification. La barre oblique inverse ( \ ) vous permet simplement de diviser la commande en plusieurs lignes. Le contenu est constitué d’en-têtes (-H), d’une méthode (-X), de données JSON (-d) si nécessaire, et de l’URL du point de terminaison. Cela va sans dire, mais ne mettez pas de scripts contenant des détails d’authentification dans des dépôts publics.
Documentation
Lorsque je suis devenu rédacteur d’API, j’ai constaté que, comme pour les autres logiciels, la documentation est souvent négligée. Mais si vous voulez que les gens utilisent vos API, elles doivent être bien documentées. Cependant, la rédaction d’API n’est pas la même chose que la rédaction technique traditionnelle. Utilisez un style d’écriture laconique et factuel. Les fragments de phrases sont souhaitables. Évitez les adjectifs et les adverbes. Vous devez fournir
Des informations complètes sur chaque composant de l’API
Les coordonnées des personnes à contacter au cas où les développeurs auraient des questions ou auraient besoin d’une assistance supplémentaire.
Des organigrammes montrant la séquence des méthodes les plus couramment utilisées pour les cas d’utilisation les plus courants.
Des guides de démarrage montrant comment développer un programme pour un cas d’utilisation courant.
Des informations sur les performances et les réglages
Des exemples de programmes illustrant les cas d’utilisation courants
Des extraits de code de travail pour chaque méthode, fonction et ressource. Il n’est pas nécessaire d’avoir des exemples complets, mais de montrer une utilisation courante de l’élément en question.
Texte de référence
L’une des limites de la génération actuelle d’outils de documentation Markdown et API est qu’ils n’offrent que peu ou pas de support pour la réutilisation automatisée du contenu (c’est pourquoi je recommande un CCMS basé sur XML pour les documents). Pour cette raison, vous devriez conserver une liste de définitions standard et d’exemples de charges utiles valides. Par exemple:
Adresse - Utilisez l’adresse principale de votre entreprise.
Barcode - 019000000002 (format UPC-A avec chiffre de contrôle)
Brand - Ownbrand (trop générique pour être enregistré en tant que marque)
Pays - USA (format ISO 3166-1 alpha-3)
Numéro de carte de crédit - 41111111111111 (Utilisez n’importe quel CVV, NOM et future DATE D’EXPIRATION. La valeur de l’achat doit être inférieure à 500 $. https://docs.stripe.com/testing)
Prénom - N’utilisez pas d’autres termes pour le prénom. Dans certaines cultures, le nom de famille précède le prénom.
GUID - 01234567-890a-bcde-f012-34567890abcd
Nom de famille - N’utilisez pas d’autres termes pour le nom de famille. Dans certaines cultures, le nom de famille précède le prénom.
Téléphone - +1 202 555 0199 (les numéros 555 se terminant par 0100-0199 sont fictifs)
URL - www.example.com (exemple.com est réservé à la documentation)
Codes de réponse HTTP
Vous devez fournir autant d’informations que possible sur les codes de réponse. Le niveau minimum acceptable de documentation est le numéro, une courte description significative et une explication des cas d’utilisation typiques.
1xx: informations
100 - Continuer.
101 - Changement de protocole.
102 - Traitement.
103 - Premiers indices.
2xx: succès
200 - Succès: Objet créé.
201 - Créé: Objet créé ou remplacé.
202 - Accepté: Traitement de la demande asynchrone.
203 - Information ne faisant pas autorité.
204 - Pas de contenu.
205 - Contenu réinitialisé.
206 - Contenu partiel
207 - Multi-statut.
208 - Déjà signalé.
226 - Manipulations d’instance utilisées.
3xx: redirection
300 - Choix multiples.
301 - Déplacé de façon permanente.
302 - Trouvé.
303 - Voir autre.
304 - Non modifié.
305 - Utiliser le proxy.
306 - Changer de proxy.
307 - Redirection temporaire.
308 - Redirection permanente.
4xx: erreurs du client
400 - Mauvaise requête: La demande n’était pas valide ou ne peut être traitée autrement. Il s’agit généralement d’une erreur de syntaxe dans la demande. Des détails supplémentaires sur l’erreur sont fournis dans le corps de la réponse.
401 - Non autorisé: Informations d’authentification manquantes ou incorrectes.
402 - Paiement requis.
403 - Interdit: La demande est comprise, mais elle a été refusée ou l’accès a été refusé. Le corps de la charge utile de la réponse fournit des détails supplémentaires sur l’erreur.
404 - Introuvable: L’URI n’est pas valide ou la ressource demandée n’existe pas.
405 - Méthode non autorisée: La ressource demandée ne supporte pas la méthode.
406 - Non acceptable.
407 - Authentification proxy requise.
408 - Délai d’attente de la demande
409 - Conflit.
410 - Parti.
411 - Longueur requise.
412 - Échec de la condition préalable.
413 - Payload too large: La demande est plus importante que ce que le serveur peut traiter.
414 - URI trop long.
415 - Type de média non pris en charge.
416 - L’intervalle ne peut être satisfait.
417 - L’attente a échoué.
418 - Je suis une théière (ne demandez pas).
421 - Requête mal dirigée.
422 - L’entité ne peut pas être traitée: La demande était bien formée, mais les données n’ont pas pu être traitées en raison d’erreurs sémantiques.
423 - Verrouillé.
424 - Échec de la dépendance.
425 - Trop tôt.
426 - Mise à niveau requise.
428 - Condition préalable requise.
429 - Trop de demandes.
431 - Champs d’en-tête de la demande trop grands.
451 - Indisponible pour des raisons légales.
5xx: erreurs du serveur
500 - Erreur interne du serveur: Il s’agit généralement d’une erreur temporaire, par exemple dans une situation de forte charge ou si un point d’accès a temporairement des problèmes.
