Comprendre les API REST - Un guide pour les impatients

Crosspost de mon article ici

REST (Représentationnel State Transfer) sont l'épine dorsale du développement Web moderne. Cet article explique comment créer et utiliser des API REST modernes, les décisions de conception à prendre en compte lors de leur création et la théorie qui constitue le fondement de REST.

Guide pratique

Cette section aborde l'utilisation des API REST avec HTTP couvrant les points de terminaison, les méthodes, les requêtes et les réponses. Vous trouverez tout ce dont vous avez besoin pour commencer à faire des appels API et à appliquer REST dans vos projets.

Comment structurer vos URI

En général, il existe deux manières principales de traiter un URI :

1. En tant que action
2. En tant que ressource

Considérez les deux URI suivants :

1. https://example.com/getUserData?id=1 (action)
2. https://example.com/users/1 (ressource)

Les deux exemples nous montrent la récupération des données utilisateur d'un utilisateur avec un identifiant de 1. La différence étant que dans le premier exemple, la route /getUserData effectue une action tandis que dans le deuxième exemple, la route /users/1 est l'emplacement de un actif, il n’indique pas quelle action est effectuée. On pourrait dire que ce type d'URI agit comme un nom (car c'est une chose au lieu d'une action, c'est-à-dire un verbe).

Le modèle REST dicte que nous utilisons strictement les URI comme dans le deuxième exemple. Nous voulons que nos URI soient des noms afin de pouvoir utiliser les méthodes HTTP comme verbes pour effectuer des actions sur ces noms. Par exemple, nous pouvons utiliser la méthode HTTP GET pour récupérer des informations sur /users/1, mais nous pourrions utiliser PUT pour mettre à jour les informations de cet utilisateur correspondant, ou DELETE pour supprimer entièrement l'utilisateur.

La dernière chose à noter à propos des URI est que, comme dans l'exemple ci-dessus, lors du référencement d'une ressource individuelle (par exemple, un seul utilisateur dans ce cas), l'URI doit se terminer par l'identifiant unique de cette ressource. Lors du référencement de toutes les ressources dans une catégorie donnée, l'identifiant unique doit être omis.

1. https://example.com/users/1 - Fait référence à un utilisateur particulier avec un identifiant de 1
2. https://example.com/users - Fait référence à tous les utilisateurs, quel que soit leur identifiant

Quelles actions soutenir

Il y a 4 actions principales à prendre en charge en REST, on utilise l'acronyme CRUD pour les mémoriser : Create, Read, U pdate, Dsupprimer. Chacune de ces actions correspond à une méthode HTTP que nous pouvons utiliser pour effectuer cette action. La cartographie est la suivante :

Toutes les combinaisons d'URI d'action à prendre en charge

Chaque API REST ne comporte en réalité que (au minimum) 5 à 6 routes. Dans notre exemple, le point de terminaison de base sera /users et nous ferons semblant de l'héberger sur https://example.com.

• OBTENIR https://example.com/users
  • Action : Renvoyer tous les actifs utilisateur (chaque actif correspond à un utilisateur)
  • Corps de la demande : Vide
  • Corps de la réponse : Liste des ressources utilisateur (sous forme de tableau JSON)
• GET https://example.com/users/[id] ([id] est une variable)
  • Action : renvoie uniquement l'actif utilisateur demandé au singulier
  • Corps de la demande : Vide
  • Corps de la réponse : juste l'actif utilisateur avec l'identifiant correspondant (au format JSON)
• POST https://example.com/users
  • Action : ajoute un actif utilisateur à la collection
  • Corps de la requête : toutes les données nécessaires pour créer le nouvel actif utilisateur (aucun format spécifique requis, JSON recommandé)
  • Corps de la réponse : l'actif nouvellement créé dans lequel un identifiant unique a été inséré (au format JSON)
• PUT https://example.com/users/[id] ([id] est une variable)
  • Action : remplace entièrement les données d'un seul utilisateur existant par les données données
  • Corps de la requête : Toutes les données nécessaires pour remplacer les données d'un utilisateur existant, qu'elles aient changé ou non (moins l'identifiant - aucun format spécifique requis, JSON recommandé)
  • Corps de la réponse : l'élément nouvellement mis à jour avec l'identifiant correspondant (au format JSON)
• (Facultatif) PATCH https://example.com/users/[id] ([id] est une variable)
  • Action : remplace partiellement les données d'un seul utilisateur existant par les données données
  • Corps de la requête : uniquement les données qui doivent être mises à jour (moins l'identifiant - aucun format spécifique requis, JSON recommandé)
  • Corps de la réponse : l'élément nouvellement mis à jour avec l'identifiant correspondant (au format JSON)
• SUPPRIMER https://example.com/users/[id] ([id] est une variable)
  • Action : Supprime un seul enregistrement de la table des utilisateurs
  • Corps de la demande : Aucun
  • Corps de la réponse : Aucun (juste le code de réponse HTTP) OU Les données de l'actif qui vient d'être supprimé avec l'identifiant correspondant (comme JSON)

Considérations de conception

En dehors de ce qui définit un point de terminaison comme utilisant ou non le modèle REST, il y a de nombreux éléments à prendre en considération avant de commencer à en créer un. Existe-t-il une possibilité que vous souhaitiez mettre à jour votre point de terminaison à l'avenir ? Votre sortie doit-elle donner des conseils utiles aux utilisateurs ? REST est-il le bon modèle à utiliser dans votre situation ? Répondons à certaines de ces questions.

Gestion des versions de votre point de terminaison

Ce serait peut-être une bonne idée de commencer à réfléchir dès le départ au versioning de votre API afin de faciliter les modifications à l'avenir. Il existe plusieurs méthodes différentes pour déterminer la version de l'API que vos utilisateurs choisissent d'utiliser :

• Gestion des versions URI
  • Les numéros de version sont incorporés dans un chemin URL, généralement à la base
  • Exemples :
  • https://example.com/v1/users/1
  • https://example.com/v2/users/1
• Paramètre de requête
  • Le numéro de version est ajouté en tant que paramètre de requête dans le point de terminaison de l'API
  • Exemples :
  • https://example.com/users/1?apiVersion=1
  • https://example.com/users/1?apiVersion=2
• Basé sur l'en-tête
  • Le numéro de version est un champ d'en-tête spécifique et unique
  • Exemples (en-têtes de demande) :
  • version x-api : 1
  • version x-api : 2
• Négociation de contenu
  • La version est déterminée en fonction de l'état de représentation ou du type de média.
  • Dans l'exemple ci-dessous, le code du serveur saurait que firstName est pour la première version et qu'il a été remplacé par gaveName dans la version suivante.
  • Exemples (corps de la demande) :
  • { prénom : 'Henry' }
  • { gaveName : 'Henry' }

Se moquer d'une API REST rapide

Parfois, jouer avec l'un d'entre eux est le meilleur outil pour apprendre comment ils fonctionnent. L'une de mes bibliothèques préférées pour la démonstration de REST est json-server. La configuration est assez simple - quelques étapes seulement sont nécessaires.

Installer le serveur JSON

npm install json-server

Créez un magasin de données simple

{
  "users": [
    { "id": "1", "username": "gorwell", "email": "gorwell@gmail.com" },
    { "id": "2", "username": "cdickens", "email": "cdickens@gmail.com" },
    { "id": "3", "username": "jausten", "email": "jausten@gmail.com" },
    { "id": "4", "username": "vwoolf", "email": "vwoolf@gmail.com" },
    { "id": "5", "username": "sking", "email": "sking@gmail.com" }
  ]
}

Démarrez le serveur

npx json-server db.json

Faites une requête HTTP sur votre serveur local

curl -X GET http://localhost:3000/users/1

Une grille de données CRUD simple

Un point de terminaison REST entièrement fonctionnel peut être facilement connecté à une grille de données avec ZingGrid, il suffit de pointer l'URI REST de base vers l'adresse l'attribut src de l'élément comme ci-dessous

<zing-grid
  src="http://localhost:3000/users"
  editor-controls
></zing-grid>

Pensées finales

Les API REST se présentent sous de nombreuses formes et tailles sur le Web, chacune étant adaptée pour répondre à des besoins spécifiques. En structurant judicieusement les URI, en choisissant les bonnes actions et en gardant à l'esprit le contrôle des versions, vous pouvez créer une API simple et flexible avec laquelle les développeurs auront plaisir à travailler. Grâce à ces étapes fondamentales, même un prototype rapide peut évoluer vers une API robuste et fiable qui résiste à l'épreuve du temps.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!