Comment fonctionnent les API REST : une requête aller-retour
Comment fonctionnent les API REST, affiché sur un canevas interactif : création d'une requête HTTP, routage et validation sur le serveur, et réponse qui complète l'aller-retour.
Une API REST est une conversation en HTTP : le client envoie une requête qui nomme une ressource et une action, le serveur la traite et la réponse comporte un code d'état et le résultat.
Comment fonctionnent les API REST : une requête aller-retour
Le canevas FlowJam interactif de cette explication : chaque couloir, ligne et flèche ci-dessus appartient à un véritable diagramme QueryChart que vous pouvez ouvrir et modifier.
Comment lire ce visuel
- Lisez les trois colonnes de gauche à droite : Requête, Traitement du serveur, Réponse.
- La ligne client et la ligne serveur alternent, donc chaque flèche représente soit le client qui envoie quelque chose, soit le serveur qui décide quelque chose.
- Le message « La demande est-elle valide ? » La décision alimente soit le chemin heureux, soit le point de terminaison Rejeter : les deux résultats que chaque appel d'API peut avoir.
La demande
"Le client crée une requête HTTP (méthode, URL, en-têtes, corps)" est le début de chaque interaction REST. La méthode est le verbe (GET lit, POST crée, PUT remplace, PATCH met à jour, DELETE supprime) et l'URL nomme la ressource, donc "/users/42" est la demande de lecture d'un utilisateur. "Le client envoie la demande via HTTPS" est le transport : REST utilise HTTP et HTTPS maintient la conversation privée sur la même infrastructure Internet que celle des autres visuels.
Le travail du serveur
"Le serveur achemine l'URL vers le gestionnaire correspondant" mappe la requête au code et "La requête est-elle valide ?" est la porte : l'authentification (qui vous êtes), l'autorisation (êtes-vous autorisé) et la validation de la charge utile se produisent toutes ici, avec des échecs envoyés au point de terminaison de rejet "Le serveur renvoie 400/401/403". "Le gestionnaire exécute la logique métier" et "Le serveur lit ou écrit la ressource dans la base de données" constituent le travail réel : la partie que le client ne voit jamais.
La réponse
"Le serveur construit la réponse avec un code d'état et un corps JSON" est le contrat sous forme machine : 200 pour le succès, 201 pour la création, 404 pour le manquant, 500 pour une panne du serveur. « Le client reçoit la réponse et l'analyse » et « Le client rend le résultat à l'utilisateur » complètent la boucle : l'aller-retour se termine là où il a commencé, dans le client, c'est exactement pourquoi le visuel revient à la ligne du client.
Relations et enseignements clés
- REST est un contrat en HTTP : les méthodes sont des verbes, les URL sont des ressources et les codes d'état sont le résultat lisible par machine.
- Le client est sans état : chaque requête contient tout ce dont le serveur a besoin, aucune session partagée n'est donc requise.
- La validation est la limite de sécurité ; une demande non valide est rejetée avant l'exécution de toute logique métier.
- La réponse est définie par son code d'état en premier et son corps en second.
- Le trafic REST utilise la même infrastructure DNS, HTTPS et Internet que la carte visuelle des autres technologies.
Quand utiliser ce visuel
- Enseigner la méthode HTTP/URL/modèle de statut aux ingénieurs avant qu'ils ne conçoivent leur premier point de terminaison.
- Examiner le contrat d'une API (les codes d'état des erreurs sont-ils ou 200 avec un indicateur ?) par rapport à la convention REST.
- Ancrer une conversation sur l'idempotence et la mise en cache dans la manière dont les demandes sont réellement créées et validées.
Comment cela fonctionne
Mappez vos propres points de terminaison sur la zone de demande
Ajoutez des notes répertoriant vos méthodes et itinéraires réels (GET/orders, POST/payments) afin que le diagramme documente la surface de votre API.
Nommez vos codes de statut
À l'étape de réponse, annotez les codes que votre API renvoie réellement pour chaque résultat et ajoutez ceux que votre contrat utilise au-delà de 200 et 400.
Ajouter une authentification
Insérez l'étape du jeton entre le client et la porte de validation (un jeton JWT ou OAuth dans l'en-tête Autorisation) pour indiquer où l'identité entre dans la demande.
Dessinez les branches de tentative et d'échec
Ajoutez des points de terminaison explicites pour les pannes de réseau, la limitation de débit et les erreurs de serveur, chacun avec le comportement du client (nouvelle tentative, interruption, état d'erreur) qu'il déclenche.
Questions fréquentes
Qu'est-ce qu'une API REST ?
Une API REST est un ensemble de points de terminaison HTTP qui exposent les ressources d'un système. Les clients agissent sur les ressources avec des méthodes HTTP (GET pour lire, POST pour créer, PUT ou PATCH pour mettre à jour, DELETE pour supprimer) et le serveur répond avec un code d'état et une représentation, généralement JSON. REST est un style plutôt qu'un standard, et sa valeur est que tout client parlant HTTP peut l'utiliser.
Quelle est la différence entre GET, POST, PUT et DELETE ?
Ce sont les verbes du contrat REST. GET lit une ressource et ne devrait avoir aucun effet secondaire. POST crée une nouvelle ressource et renvoie son identité. PUT remplace en gros une ressource et est idempotent : la répéter ne change rien de plus. PATCH applique une mise à jour partielle. DELETE supprime une ressource. Ensemble, les verbes et l'URL nomment l'action complète, c'est pourquoi la zone de requête dans le visuel appelle d'abord la méthode.
Pourquoi les codes d’état sont-ils importants dans REST ?
Parce qu’ils constituent le résultat lisible par machine de la demande. Un client peut bifurquer sur le code d'état sans analyser le corps : 2xx succès, 4xx erreur du client, 5xx celle du serveur. Les API qui renvoient 200 avec un indicateur d'erreur dans le corps rompent ce contrat et obligent chaque client à utiliser une casse particulière pour la réponse.
Qu'est-ce qui rend une API « RESTful » ?
La liste de contrôle pratique : des ressources nommées par URL, des actions exprimées sous forme de méthodes HTTP, des requêtes sans état (chacune transporte tout ce dont le serveur a besoin), des réponses qui utilisent correctement les codes d'état et souvent des URL hypermédia ou versionnées. Le canevas modélise l'aller-retour (demande, validation, traitement, réponse) qui est la forme partagée par chaque échange RESTful.
Modifier ce visuel dans QueryChart (FlowJam)
Ouvrez ce canevas REST exact en tant que votre propre graphique, renommez le client et le serveur en vos services et annotez vos points de terminaison.