Meilleures pratiques pour la création d'API REST

salut!



Cet article, malgré son titre innocent, a provoqué une discussion tellement verbeuse sur Stackoverflow que nous ne pouvions pas passer outre. Une tentative pour saisir l'immensité - pour parler clairement de la conception compétente de l'API REST - apparemment, l'auteur a réussi à bien des égards, mais pas complètement. En tout cas, nous espérons rivaliser avec l'original dans le degré de discussion, ainsi que le fait que nous rejoindrons l'armée de fans d'Express.



Bonne lecture!



Les API REST sont l'un des types de services Web les plus courants disponibles aujourd'hui. Avec leur aide, divers clients, y compris des applications de navigateur, peuvent échanger des informations avec le serveur via l'API REST.



Par conséquent, il est très important de concevoir correctement l'API REST afin de ne pas avoir de problèmes en cours de route. Considérez la sécurité, les performances et la convivialité de l'API du point de vue du consommateur.



Sinon, nous provoquerons des problèmes pour les clients utilisant nos API - ce qui est frustrant et ennuyeux. Si nous ne respectons pas les conventions communes, nous ne ferons que confondre ceux qui maintiendront notre API, ainsi que les clients, car l'architecture sera différente de celle que tout le monde s'attend à voir.



Cet article examinera comment concevoir des API REST de manière à ce qu'elles soient simples et compréhensibles pour tous ceux qui les utilisent. Nous assurerons leur pérennité, leur sécurité et leur rapidité, car les données transférées aux clients via une telle API peuvent être confidentielles.



Puisqu'il existe de nombreuses raisons et options pour qu'une application réseau échoue, nous devons nous assurer que les erreurs dans toute API REST sont gérées avec élégance et accompagnées de codes HTTP standard pour aider le consommateur à résoudre le problème.

Acceptez JSON et renvoyez JSON en réponse

Les API REST doivent accepter JSON pour la charge utile de la requête et également envoyer des réponses JSON. JSON est une norme de transfert de données. Presque toutes les technologies réseau sont adaptées pour l'utiliser: JavaScript a des méthodes intégrées pour encoder et décoder JSON, soit via l'API Fetch, soit via un autre client HTTP. Les technologies côté serveur utilisent des bibliothèques pour décoder JSON avec peu ou pas d'intervention de votre part.



Il existe d'autres moyens de transférer des données. XML en tant que tel n'est pas très largement pris en charge dans les frameworks; vous devez généralement convertir les données dans un format plus pratique, qui est généralement JSON. Côté client, en particulier dans le navigateur, il n'est pas si simple de traiter ces données. Vous devez faire beaucoup de travail supplémentaire juste pour assurer le transfert normal des données.



Les formulaires sont pratiques pour transférer des données, surtout si nous allons transférer des fichiers. Mais pour transférer des informations sous forme de texte et numérique, vous pouvez vous passer de formulaires, car la plupart des frameworks permettent le transfert JSON sans traitement supplémentaire - prenez simplement les données côté client. C'est la manière la plus simple de les gérer.



Pour garantir que le client interprète le JSON reçu de notre API REST exactement comme JSON, Content-Typel'en-tête de réponse doit être défini sur une valeur une application/jsonfois la demande effectuée. De nombreux frameworks d'application côté serveur définissent automatiquement l'en-tête de réponse. Certains clients HTTP regardent Content-Typedans l'en-tête de la réponse et analysent les données selon le format qui y est spécifié.



La seule exception se produit lorsque nous essayons d'envoyer et de recevoir des fichiers qui sont transférés entre le client et le serveur. Ensuite, vous devez traiter les fichiers reçus en tant que réponse et envoyer les données du formulaire du client au serveur. Mais c'est un sujet pour un autre article.



Nous devons également nous assurer que JSON est la réponse de nos points de terminaison. De nombreux frameworks de serveur intègrent cette fonctionnalité.



Prenons un exemple d'API qui accepte une charge utile JSON. Cet exemple utilise le framework de backend Express pour Node.js. Nous pouvons utiliser un programme comme middleware body-parserpour analyser le corps de la requête JSON, puis appeler une méthode res.jsonavec l'objet que nous voulons renvoyer en tant que réponse JSON. Ceci est fait comme ceci:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

app.use(bodyParser.json());

app.post('/', (req, res) => {
  res.json(req.body);
});

app.listen(3000, () => console.log('server started'));

bodyParser.json()analyse la chaîne du corps de la demande en JSON, la convertit en objet JavaScript, puis attribue le résultat à l'objet req.body.



Définissez l'en-tête Content-Type dans la réponse sur une valeur application/json; charset=utf-8sans aucune modification. La méthode présentée ci-dessus est applicable à la plupart des autres frameworks backend.

Nous utilisons des noms pour les chemins vers les points de terminaison, pas des verbes

Les noms des chemins vers les points de terminaison ne doivent pas être des verbes, mais des noms. Ce nom représente l'objet du point de terminaison, que nous récupérons à partir de là, ou que nous manipulons.



Le fait est que le nom de notre méthode de requête HTTP contient déjà un verbe. Mettre des verbes dans les noms des chemins vers le point de terminaison de l'API n'est pas pratique; de plus, le nom s'avère inutilement long et ne contient aucune information valable. Les verbes choisis par le développeur peuvent être mis simplement en fonction de son caprice. Par exemple, certaines personnes préfèrent l'option 'get', et d'autres préfèrent 'retrieve', il est donc préférable de vous limiter au verbe HTTP GET familier qui vous indique ce que fait le point de terminaison.



L'action doit être spécifiée dans le nom de la méthode HTTP de la requête que nous faisons. Les méthodes les plus courantes contiennent les verbes GET, POST, PUT et DELETE.

GET récupère les ressources. POST envoie de nouvelles données au serveur. PUT met à jour les données existantes. DELETE supprime les données. Chacun de ces verbes correspond à l'une des opérations du groupe CRUD .



Compte tenu des deux principes évoqués ci-dessus, afin de recevoir de nouveaux articles, nous devons créer des itinéraires de la forme GET /articles/. De même, nous utilisons POST /articles/pour mettre à jour un nouvel article, PUT /articles/:id pour mettre à jour un article avec celui donné id. La méthode DELETE est /articles/:idconçue pour supprimer un article avec un ID donné.



/articlesEst une ressource API REST. Par exemple, vous pouvez utiliser Express pour effectuer les opérations suivantes avec des articles:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

app.use(bodyParser.json());

app.get('/articles', (req, res) => {
  const articles = [];
  //    ...
  res.json(articles);
});

app.post('/articles', (req, res) => {
  //     ...
  res.json(req.body);
});

app.put('/articles/:id', (req, res) => {
  const { id } = req.params;
  //    ...
  res.json(req.body);
});

app.delete('/articles/:id', (req, res) => {
  const { id } = req.params;
  //    ...
  res.json({ deleted: id });
});

app.listen(3000, () => console.log('server started'));

Dans le code ci-dessus, nous avons défini des points de terminaison pour manipuler les articles. Comme vous pouvez le voir, il n'y a pas de verbes dans les noms de chemin. Noms seulement. Les verbes ne sont utilisés que dans les noms des méthodes HTTP.



Les points de terminaison POST, PUT et DELETE acceptent un corps de requête JSON et renvoient une réponse JSON, y compris un point de terminaison GET.

Les collections sont appelées noms pluriels

Les collections doivent être nommées avec des noms pluriels. Ce n'est pas souvent que nous devons prendre un seul élément d'une collection, nous devons donc être cohérents et utiliser des noms pluriels dans les noms de collection.



Le pluriel est également utilisé pour assurer la cohérence avec les conventions de dénomination dans les bases de données. En règle générale, une table ne contient pas un, mais plusieurs enregistrements et la table est nommée en conséquence.



Lorsque vous travaillez avec un point de terminaison, /articlesnous utilisons le pluriel pour nommer tous les points de terminaison.

Imbrication de ressources lors de l'utilisation d'objets hiérarchiques

Le chemin des points de terminaison traitant des ressources imbriquées doit être structuré comme ceci: ajoutez la ressource imbriquée comme chemin d'accès après le nom de la ressource parente.

Vous devez vous assurer que dans votre code, l'imbrication des ressources correspond exactement à l'imbrication des informations dans nos tables de base de données. Sinon, la confusion est possible.



Par exemple, si nous voulons recevoir des commentaires sur un nouvel article à un certain point de terminaison, nous devons attacher le chemin / les commentaires à la fin du chemin /articles. Dans ce cas, on suppose que nous considérons l'entité de commentaires comme une entité enfant articledans notre base de données.



Par exemple, vous pouvez le faire avec le code suivant dans Express:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

app.use(bodyParser.json());

app.get('/articles/:articleId/comments', (req, res) => {
  const { articleId } = req.params;
  const comments = [];
  //      articleId
  res.json(comments);
});


app.listen(3000, () => console.log('server started'));

Dans le code ci-dessus, vous pouvez utiliser la méthode GET sur le chemin '/articles/:articleId/comments'. Nous recevons des commentaires commentssur l'article correspondant articleId, puis nous le renvoyons en réponse. Nous ajoutons 'comments'après le segment de chemin '/articles/:articleId'pour indiquer qu'il s'agit d'une ressource enfant /articles.



Cela a du sens car les commentaires sont des objets enfants articleset il est supposé que chaque article a son propre ensemble de commentaires. Sinon, cette structure peut prêter à confusion pour l'utilisateur, car elle est généralement utilisée pour accéder aux objets enfants. Le même principe s'applique lorsque vous travaillez avec des points de terminaison POST, PUT et DELETE. Ils utilisent tous la même structure d'imbrication lors de la construction des noms de chemin.

Traitement soigné des erreurs et renvoyer les codes d'erreur standard

Pour éviter toute confusion lorsqu'une erreur se produit sur l'API, gérez les erreurs avec soin et renvoyez des codes de réponse HTTP indiquant quelle erreur s'est produite. Cela fournit aux responsables de l'API des informations suffisantes pour comprendre le problème. Il est inacceptable que des erreurs plantent le système, par conséquent, elles ne peuvent pas être laissées sans traitement, et le consommateur d'API doit faire face à un tel traitement.



Les codes d'erreur HTTP les plus courants sont:

• 400 Bad Request - Indique que l'entrée reçue du client a échoué à la validation.
• 401 Non autorisé - signifie que l'utilisateur ne s'est pas connecté et n'a donc pas l'autorisation d'accéder à la ressource. En règle générale, ce code est émis lorsque l'utilisateur n'est pas authentifié.
• 403 Interdit - Indique que l'utilisateur est authentifié mais n'est pas autorisé à accéder à la ressource.
• 404 Not Found - signifie que la ressource n'a pas été trouvée
• L'erreur de serveur interne 500 est une erreur de serveur et ne devrait probablement pas être renvoyée explicitement.
• 502 Bad Gateway - Indique un message de réponse non valide du serveur en amont.
• 503 Service indisponible - signifie que quelque chose d'inattendu s'est produit côté serveur - par exemple, surcharge du serveur, défaillance de certains éléments du système, etc.

Vous devez émettre exactement les codes qui correspondent à l'erreur qui a empêché notre application. Par exemple, si nous voulons rejeter les données reçues en tant que charge utile de requête, alors, conformément aux règles de l'API Express, nous devons renvoyer un code de 400:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

//  
const users = [
  { email: 'abc@foo.com' }
]

app.use(bodyParser.json());

app.post('/users', (req, res) => {
  const { email } = req.body;
  const userExists = users.find(u => u.email === email);
  if (userExists) {
    return res.status(400).json({ error: 'User already exists' })
  }
  res.json(req.body);
});


app.listen(3000, () => console.log('server started'));

Dans le code ci-dessus, nous conservons dans le tableau des utilisateurs une liste d'utilisateurs existants qui ont des e-mails connus.



De plus, si nous essayons d'envoyer une charge utile avec une valeur emaildéjà présente dans les utilisateurs, nous obtenons une réponse avec un code de 400 et un message 'User already exists'indiquant qu'un tel utilisateur existe déjà. Avec ces informations, l'utilisateur peut s'améliorer - remplacez l'adresse e-mail par celle qui ne figure pas encore sur la liste.



Les codes d'erreur doivent toujours être accompagnés de messages suffisamment informatifs pour corriger l'erreur, mais pas suffisamment détaillés pour que ces informations puissent être utilisées par des attaquants qui ont l'intention de voler nos informations ou de planter le système.



Chaque fois que notre API ne parvient pas à s'arrêter correctement, nous devons gérer soigneusement l'échec en envoyant des informations d'erreur pour faciliter la correction de la situation par l'utilisateur.

Autoriser le tri, le filtrage et la pagination des données

Les bases derrière l'API REST peuvent beaucoup évoluer. Parfois, il y a tellement de données qu'il est impossible de les récupérer toutes en même temps, car cela ralentira le système ou même le fera tomber. Par conséquent, nous avons besoin d'un moyen de filtrer les éléments.



Nous avons également besoin de moyens pour paginer les données (pagination) afin de ne renvoyer que quelques résultats à la fois. Nous ne voulons pas prendre trop de temps sur les ressources pour essayer d'extraire toutes les données demandées à la fois.



Le filtrage et la pagination des données peuvent améliorer les performances en réduisant l'utilisation des ressources du serveur. Plus les données s'accumulent dans la base de données, plus ces deux possibilités deviennent importantes.



Voici un petit exemple où l'API peut accepter une chaîne de requête avec divers paramètres. Filtrons les éléments par leurs champs:

const express = require('express');
const bodyParser = require('body-parser');

const app = express();

//      
const employees = [
  { firstName: 'Jane', lastName: 'Smith', age: 20 },
  //...
  { firstName: 'John', lastName: 'Smith', age: 30 },
  { firstName: 'Mary', lastName: 'Green', age: 50 },
]

app.use(bodyParser.json());

app.get('/employees', (req, res) => {
  const { firstName, lastName, age } = req.query;
  let results = [...employees];
  if (firstName) {
    results = results.filter(r => r.firstName === firstName);
  }

  if (lastName) {
    results = results.filter(r => r.lastName === lastName);
  }

  if (age) {
    results = results.filter(r => +r.age === +age);
  }
  res.json(results);
});

app.listen(3000, () => console.log('server started'));

Dans le code ci-dessus, nous avons une variable req.queryqui nous permet d'obtenir des paramètres de requête. Nous pouvons ensuite extraire les valeurs de propriété en déstructurant les paramètres de requête individuels en variables; JavaScript a une syntaxe spéciale pour cela.



Enfin, nous appliquons un filtre sur chaque valeur de paramètre de requête pour trouver les éléments que nous voulons retourner.



Cela fait, nous renvoyons les résultats en tant que réponse. Par conséquent, lorsque vous effectuez une requête GET vers le chemin suivant avec une chaîne de requête:

/employees?lastName=Smith&age=30

On a:

[
    {
        "firstName": "John",
        "lastName": "Smith",
        "age": 30
    }
]

comme réponse renvoyée car le filtrage était activé lastNameet age.



De même, vous pouvez accepter le paramètre de requête de page et renvoyer un groupe d'enregistrements occupant des positions de (page - 1) * 20à page * 20.



Également dans la chaîne de requête, vous pouvez spécifier les champs par lesquels le tri sera effectué. Dans ce cas, nous pouvons les trier par ces champs séparés. Par exemple, nous pouvons avoir besoin d'extraire une chaîne de requête d'une URL comme celle-ci:

http://example.com/articles?sort=+author,-datepublished

Où +signifie «haut» et –«bas». Nous trions donc par nom d'auteur par ordre alphabétique et par date de publication du plus récent au plus ancien.

Adhérez à des pratiques de sécurité éprouvées

La communication entre le client et le serveur doit être principalement privée, car nous envoyons et recevons souvent des informations confidentielles. Par conséquent, l'utilisation de SSL / TLS pour la sécurité est un must.



Le certificat SSL n'est pas si difficile à télécharger sur le serveur, et le certificat lui-même est soit gratuit, soit très bon marché. Il n'y a aucune raison de renoncer à permettre à nos API REST de communiquer sur des canaux sécurisés plutôt que sur des canaux ouverts.



Une personne ne doit pas avoir accès à plus d'informations que ce qu'elle a demandé. Par exemple, un utilisateur ordinaire ne devrait pas avoir accès aux informations d'un autre utilisateur. De plus, il ne devrait pas pouvoir afficher les données des administrateurs.



Pour promouvoir le principe du moindre privilège, vous devez soit implémenter la vérification des rôles pour un rôle spécifique, soit fournir une plus grande granularité des rôles pour chaque utilisateur.



Si nous décidons de regrouper les utilisateurs en plusieurs rôles, les rôles doivent être dotés de tels droits d'accès qui garantissent que tout ce dont l'utilisateur a besoin est fait et rien de plus. Si nous prescrivons plus en détail les droits d'accès à chaque opportunité fournie à l'utilisateur, nous devons nous assurer que l'administrateur peut accorder ces capacités à n'importe quel utilisateur ou retirer ces capacités. En outre, vous devez ajouter des rôles prédéfinis pouvant être appliqués à un groupe d'utilisateurs afin de ne pas avoir à définir manuellement les droits nécessaires pour chaque utilisateur.

Mettez en cache les données pour améliorer les performances

La mise en cache peut être ajoutée pour renvoyer des données à partir d'une mémoire cache locale, plutôt que de récupérer certaines données de la base de données chaque fois que les utilisateurs le demandent. L'avantage de la mise en cache est que les utilisateurs peuvent récupérer les données plus rapidement. Cependant, ces données peuvent être obsolètes. Cela peut également être source de problèmes lors du débogage dans les environnements de production, lorsque quelque chose ne va pas et que nous continuons à examiner les anciennes données.



Il existe une variété d'options de mise en cache disponibles, telles que Redis , la mise en cache en mémoire, etc. Vous pouvez modifier la façon dont les données sont mises en cache selon vos besoins.



Par exemple, Express fournit un middlewareapicachepour ajouter une capacité de mise en cache à votre application sans configuration compliquée. Une simple mise en cache en mémoire peut être ajoutée au serveur comme ceci:

const express = require('express');

const bodyParser = require('body-parser');
const apicache = require('apicache');
const app = express();
let cache = apicache.middleware;
app.use(cache('5 minutes'));

//      
const employees = [
  { firstName: 'Jane', lastName: 'Smith', age: 20 },
  //...
  { firstName: 'John', lastName: 'Smith', age: 30 },
  { firstName: 'Mary', lastName: 'Green', age: 50 },
]

app.use(bodyParser.json());

app.get('/employees', (req, res) => {
  res.json(employees);
});

app.listen(3000, () => console.log('server started'));

Le code ci-dessus fait simplement référence à apicacheavec apicache.middleware, ce qui donne:

app.use(cache('5 minutes'))

et cela suffit pour appliquer la mise en cache à l'échelle de l'application. Nous mettons en cache, par exemple, tous les résultats en cinq minutes. Par la suite, cette valeur peut être ajustée en fonction de ce dont nous avons besoin.

Gestion des versions d'API

Nous avons besoin de différentes versions de l'API au cas où nous y apporterions des modifications susceptibles de perturber le client. Le versionnage peut être effectué sur une base sémantique (par exemple, 2.0.6 signifie que la version principale est 2, et c'est le sixième patch). Ce principe est désormais accepté dans la plupart des applications.



De cette façon, vous pouvez progressivement retirer les anciens points de terminaison plutôt que de forcer tout le monde à basculer simultanément vers la nouvelle API. Vous pouvez enregistrer la version v1 pour ceux qui ne veulent rien changer, et fournir la version v2 avec toutes ses nouvelles fonctionnalités pour ceux qui sont prêts à la mise à niveau. Ceci est particulièrement important dans le contexte des API publiques. Ils doivent être versionnés pour éviter de casser les applications tierces qui utilisent nos API.



Le contrôle de version est généralement effectué en ajoutant /v1/,/v2/, etc., ajouté au début du chemin de l'API.



Par exemple, voici comment procéder dans Express:

const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.json());

app.get('/v1/employees', (req, res) => {
  const employees = [];
  //      
  res.json(employees);
});

app.get('/v2/employees', (req, res) => {
  const employees = [];
  //       
  res.json(employees);
});

app.listen(3000, () => console.log('server started'));

Nous ajoutons simplement le numéro de version au début du chemin menant au point de terminaison.

Conclusion

La chose la plus importante à retenir de la conception d'API REST de haute qualité est de maintenir la cohérence en suivant les normes et les conventions du Web. Les codes d'état JSON, SSL / TLS et HTTP sont aujourd'hui incontournables sur le Web.



La performance est tout aussi importante. Vous pouvez l'augmenter sans renvoyer trop de données à la fois. De plus, vous pouvez utiliser la mise en cache pour éviter de demander sans cesse les mêmes données.



Les chemins d'accès aux points de terminaison doivent être nommés de manière cohérente. Vous devez utiliser des noms dans leurs noms, car les verbes sont présents dans les noms des méthodes HTTP. Les chemins d'accès aux ressources imbriquées doivent suivre le chemin d'accès aux ressources parent. Ils doivent communiquer ce que nous recevons ou manipulons, afin que nous n'ayons pas à consulter en plus la documentation pour comprendre ce qui se passe.