Fermer

février 5, 2020

Savez-vous ce qu'est une API REST? –


REST est l'acronyme de Representational State Transfer – une description presque dénuée de sens de la technologie de service Web la plus utilisée! REST est un moyen pour deux systèmes informatiques de communiquer via HTTP de la même manière que les navigateurs Web et les serveurs.

Le partage de données entre deux systèmes ou plus a toujours été une exigence fondamentale du développement logiciel. Par exemple, pensez à souscrire une assurance automobile. Votre assureur doit obtenir des informations sur vous et votre véhicule afin de demander des données aux autorités d'immatriculation des voitures, aux agences de crédit, aux banques et à d'autres systèmes. Tout cela se produit de manière transparente en temps réel pour déterminer si une stratégie peut être proposée.

Cet article populaire a été mis à jour en 2020 pour expliquer avec précision les API REST modernes.

Exemple REST

Ouvrez le lien suivant dans votre navigateur pour demander une blague de programmation aléatoire:

https://official-joke-api.appspot.com/jokes/programming/random

Il s'agit d'une API publique implémentée en tant que service Web RESTful (elle suit les conventions REST). Votre navigateur affichera une horrible blague de programmation au format JSON, comme:

[
  {
    "id": 29,
    "type": "programming",
    "setup": "There are 10 types of people in this world...",
    "punchline": "Those who understand binary and those who don't"
  }
]

Vous pouvez demander la même URL et obtenir une réponse en utilisant n'importe quel client HTTP, comme curl : [19659009] curl "https://official-joke-api.appspot.com/jokes/programming/random"

Les bibliothèques client HTTP sont disponibles dans tous les langages et temps d'exécution courants, y compris Récupérer en JavaScript et file_get_contents () en PHP . Une réponse JSON est lisible par machine afin de pouvoir être analysée et sortie en HTML ou tout autre format.

REST et le reste

Diverses normes de communication de données ont évolué au fil des ans. Vous avez peut-être rencontré des normes telles que CORBA SOAP ou XML-RPC qui établissaient généralement des règles de messagerie strictes.

REST a été défini en 2000 par Roy Fielding et est considérablement plus simple. Ce n'est pas une norme mais un ensemble de recommandations et de contraintes pour les services Web RESTful. Ceux-ci incluent:

  1. Client-Serveur . SystemA envoie une requête HTTP à une URL hébergée par SystemB, qui renvoie une réponse.

    C'est identique au fonctionnement d'un navigateur. L'application fait une demande pour une URL spécifique. La demande est acheminée vers un serveur Web qui renvoie une page HTML. Cette page peut contenir des références à des images, à des feuilles de style et à JavaScript, ce qui entraîne d'autres demandes et réponses.

  2. Apatride . REST est sans état: la demande du client doit contenir toutes les informations nécessaires pour répondre à une demande. En d'autres termes, il devrait être possible de faire deux ou plusieurs requêtes HTTP dans n'importe quel ordre et les mêmes réponses seront reçues.

  3. Cacheable . Une réponse doit être définie comme pouvant être mise en cache ou non.

  4. Layered . Le client demandeur n'a pas besoin de savoir s'il communique avec le serveur réel, un proxy ou tout autre intermédiaire.

Création d'un service Web RESTful

Une demande de service Web RESTful contient:

  1. Une URL de point de terminaison . Une application implémentant une API RESTful définira un ou plusieurs points de terminaison URL avec un domaine, un port, un chemin et / ou une chaîne de requête – par exemple, https: // mondomaine / utilisateur / 123? Format = json . [19659016] La méthode HTTP . Différentes méthodes HTTP peuvent être utilisées sur n'importe quel point de terminaison mappant à des opérations de création, de lecture, de mise à jour et de suppression (CRUD):

    Méthode HTTP CRUD Action
    GET lire renvoie les données demandées
    POST create crée un nouvel enregistrement
    PUT or PATCH update met à jour un enregistrement existant
    DELETE delete supprime un enregistrement existant

    Exemples:

    • une demande GET à / user / renvoie une liste d'utilisateurs enregistrés sur un système
    • une demande POST à ​​ / user / 123 crée un utilisateur avec l'ID 123 en utilisant les données du corps
    • une demande PUT à / user / 123 met à jour l'utilisateur 123 avec le ] body data
    • une demande GET à / user / 123 renvoie les détails de l'utilisateur 123
    • une demande DELETE à / user / 123 supprime l'utilisateur 123
  2. En-têtes HTTP . Des informations telles que jetons d'authentification ou cookies peuvent être contenues dans l'en-tête de demande HTTP.

  3. Body Data . Les données sont normalement transmises dans le corps HTTP d'une manière identique aux soumissions HTML

    ou en envoyant une seule chaîne de données codée JSON.

La ​​réponse

La réponse réponse peut être ce qui est pratique: données, HTML, une image, un fichier audio, etc. Les réponses aux données sont généralement codées en JSON, mais XML, CSV, des chaînes simples ou tout autre format peuvent être utilisés. Vous pouvez autoriser le format de retour à être spécifié dans la demande – par exemple, / user / 123? Format = json ou / user / 123? Format = xml .

Un le code d'état HTTP approprié doit également être défini dans l'en-tête de réponse. 200 OK est le plus souvent utilisé pour les demandes réussies, bien que 201 créé puisse également être renvoyé lorsqu'un enregistrement est créé. Les erreurs doivent renvoyer un code approprié tel que 400 Bad Request 404 Not Found 401 Unauthorized etc.

D'autres en-têtes HTTP peuvent être définis y compris les directives Cache-Control ou Expires pour spécifier combien de temps une réponse peut être mise en cache avant d'être considérée périmée .

Cependant, il n'y a pas de règles strictes . Les URL de point de terminaison, les méthodes HTTP, les données de corps et les types de réponse peuvent être implémentés à votre guise. Par exemple, POST, PUT et PATCH sont souvent utilisés de manière interchangeable, de sorte que chacun créera ou mettra à jour un enregistrement.

Exemple «Hello World» REST

Le code suivant crée un service Web RESTful à l'aide du Node.js Cadre express . Un seul point de terminaison / hello / répond aux demandes GET.

Assurez-vous que Node.js est installé, puis créez un nouveau dossier nommé restapi . Créez un nouveau fichier package.json dans ce dossier avec le contenu suivant:

 {
  "nom": "restapi",
  "version": "1.0.0",
  "description": "test REST",
  "scripts": {
    "start": "node ./index.js"
  },
  "dépendances": {
    "express": "4.17.1"
  }
}

Exécutez npm install à partir de la ligne de commande pour récupérer les dépendances, puis créez un fichier index.js avec le code suivant:

 // simple Express.js RESTful API
«utiliser strictement»;

// initialiser
const
  port = 8888,
  express = besoin ('express'),
  app = express ();

// / bonjour / demande GET
app.get ('/ bonjour /: nom?', (req, res) =>
  res.json (
    {message: `Bonjour $ {req.params.name || 'monde'}! `}
  )
);

// démarre le serveur
app.listen (port, () =>
  console.log (`Le serveur a démarré sur le port $ {port}`);
);

Lancez l'application à partir de la ligne de commande à l'aide de npm start et ouvrez http: // localhost: 8888 / hello / dans un navigateur. Le JSON suivant s'affiche en réponse à la demande GET:

 {
  "message": "Bonjour tout le monde!"
}

L'API autorise également un nom personnalisé, donc http: // localhost: 8888 / bonjour / tout le monde / renvoie:

 {
  "message": "Bonjour à tous!"
}

Demandes REST côté client et CORS

Considérez la page HTML suivante lancée dans un navigateur à l'URL http: // localhost: 8888 / :





 Test REST   

L'appel de récupération affiche la même demande d'API et la même console de navigateur Objet {message: "Bonjour tout le monde!" } comme vous vous y attendez.

Cependant, supposez que votre service Web RESTful soit désormais mis en ligne sur le Web dans le domaine http://mydomain.com/hello/ . La page JavaScript fetch () URL est modifiée en conséquence, mais l'ouverture de http: // localhost: 8888 / dans le navigateur renvoie désormais l'erreur de console Demande d'origine croisée bloquée .

Pour des raisons de sécurité, les navigateurs n'autorisent que les appels côté client XMLHttpRequest et Fetch API vers le même domaine où la page est hébergée.

Heureusement, Le partage de ressources d'origine croisée (CORS) nous permet de contourner cette restriction de sécurité. Définition d'un En-tête de réponse HTTP Access-Control-Allow-Origin indique aux navigateurs d'autoriser la demande. Il peut être défini sur un domaine spécifique ou * pour tous les domaines (effectué par l'API Joke ci-dessus).

Le code API du service Web peut donc être modifié pour autoriser l'accès à partir de n'importe quel script côté client exécutant sur n'importe quel domaine:

 // / bonjour / demande GET
app.get ('/ bonjour /: nom?', (req, res) =>
  res
    .append ('Access-Control-Allow-Origin', '*')
    .json (
      {message: `Bonjour $ {req.params.name || 'monde'}! `}
    )
);

Alternativement, une fonction middleware Express.js pourrait ajouter l'en-tête à chaque demande de point de terminaison:

 // enable CORS
app.use ((req, res, next) => {
  res.append ('Access-Control-Allow-Origin', '*');
  suivant();
});

// / bonjour / demande GET
// ...

Défis REST

Le succès de REST doit beaucoup à sa simplicité. Les développeurs sont libres d'implémenter les API RESTful comme ils le souhaitent, mais cela peut entraîner d'autres défis.

Consensus sur les points finaux

Considérez les points finaux suivants:

  • / user / 123
  • / user / id / 123
  • / user /? id = 123

Toutes ces options sont valides pour récupérer des données pour l'utilisateur 123 . Le nombre de combinaisons augmente encore lorsque vous avez des opérations plus complexes. Par exemple, renvoyez dix utilisateurs dont le nom de famille commence par «A» et travaillez pour companyX à partir de l'enregistrement 51 lorsqu'ils sont classés par date de naissance dans l'ordre chronologique inverse.

En fin de compte, peu importe la façon dont vous formatez les URL, mais la cohérence entre votre API est importante. Cela peut être difficile à réaliser sur de grandes bases de code avec de nombreux développeurs.

Versioning de l'API

Les modifications de l'API sont inévitables, mais les URL de point de terminaison ne doivent jamais être invalidées lorsqu'elles sont utilisées en interne et / ou par des applications tierces. [19659013] Les API sont souvent versionnées pour éviter les problèmes de compatibilité – tels que /2.0/user/123 remplace / user / 123 – mais l'ancien point final reste actif. Cependant, cela augmente la charge de travail, car plusieurs API sont maintenues. Les API plus anciennes peuvent éventuellement être supprimées, mais le processus nécessite une planification minutieuse.

Authentification

L'API Joke présentée ci-dessus est ouverte : tout système peut récupérer une blague sans autorisation. Cela n'est pas viable pour les API qui accèdent à des données privées ou permettent des demandes de mise à jour et de suppression.

Les applications côté client sur le même domaine que l'API RESTful enverront et recevront des cookies comme n'importe quelle autre requête HTTP. (Notez que Fetch () dans les anciens navigateurs nécessite la définition de informations d'identification option init .) Une demande d'API peut donc être validée pour garantir qu'un utilisateur est connecté et a

Les applications tierces doivent utiliser d'autres méthodes d'autorisation. Les options d'authentification courantes incluent:

  1. Authentification de base HTTP . Un en-tête HTTP Autorisation contenant un nom d'utilisateur codé en base64: une chaîne de mot de passe est transmise dans l'en-tête de la demande.
  2. Clés API . Une application tierce est autorisée à utiliser une API en émettant une clé qui peut avoir des droits spécifiques ou être limitée à un domaine particulier. La clé est transmise dans chaque requête dans l'en-tête HTTP ou sur la chaîne de requête.
  3. OAuth . Un jeton est obtenu avant que toute demande puisse être effectuée en envoyant un ID client et éventuellement un secret client à un serveur OAuth. Le jeton OAuth est ensuite envoyé avec chaque demande d'API jusqu'à son expiration.
  4. Jetons Web JSON (JWT) . Les jetons d'authentification signés numériquement sont transmis en toute sécurité dans l'en-tête de demande et de réponse.

L'authentification API variera selon le contexte d'utilisation. Dans certains cas, l'application tierce est considérée comme un autre utilisateur connecté avec des droits et autorisations spécifiques – par exemple, lors de la génération d'itinéraires à partir d'une API de carte. Dans d'autres cas, l'application tierce est utilisée par un utilisateur enregistré et ne peut accéder qu'à ses données, par exemple lors de la récupération de contenu ou de documents électroniques.

Sécurité

Une API RESTful fournit une autre voie d'accès et de manipulation ton application. Même si ce n'est pas une cible de piratage intéressante, un client mal comporté peut envoyer des milliers de requêtes chaque seconde et planter votre serveur.

La sécurité dépasse le cadre de cet article, mais les meilleures pratiques courantes incluent:

  • utilisez HTTPS [19659040] utiliser une méthode d'authentification robuste
  • utiliser CORS pour limiter les appels côté client vers des domaines spécifiques
  • fournir une fonctionnalité minimale – c'est-à-dire, ne pas créer d'options SUPPRIMER qui ne sont pas nécessaires
  • valident toutes les URL de point de terminaison et les données de corps
  • évitent d'exposer les jetons d'API en JavaScript côté client
  • bloquent l'accès à partir de domaines ou d'adresses IP inconnus
  • bloquent des charges utiles inattendues
  • envisagent une limitation de débit – c'est-à-dire que les demandes utilisant le même jeton d'API ou la même adresse IP sont limitées à N par minute
  • répondent avec un code d'état HTTP approprié et la mise en cache l'en-tête des demandes de journal et enquêtent les échecs

Demandes multiples et données inutiles

Les API RESTful sont limitées par leur implémentation. Une réponse peut contenir plus de données que vous n'en avez besoin, ou nécessiter de nouvelles demandes pour accéder à toutes les données.

Envisagez une API RESTful qui donne accès aux données d'auteur et de livre. Pour afficher les données des 10 livres les plus vendus, le client doit:

  1. Demander les 10 premiers / livre / détails classés par nombre de ventes (le plus vendu en premier). La réponse contient une liste de livres avec chaque ID d'auteur.
  2. Jusqu'à 10 / author / {id} requêtes pour récupérer le nom de chaque auteur.

Ceci est connu sous le nom de N +1 problème ;

S'il s'agit d'un cas d'utilisation courant, l'API RESTful peut être modifiée de sorte que chaque livre renvoyé contienne les détails complets de l'auteur tels que leur nom, leur âge, leur pays, biographie, etc. Il pourrait également fournir tous les détails de leurs autres livres – bien que cela augmenterait considérablement la charge utile de réponse!

Pour éviter des réponses massives, l'API pourrait être ajustée afin que les détails de l'auteur puissent être contrôlés – par exemple, ? Author_details = basic – mais le nombre d'options peut rapidement devenir déroutant.

Est-ce que GraphQL corrige REST?

Ces énigmes REST ont conduit Facebook à créer GraphQL – une requête de service Web Langue. Considérez-le comme SQL pour les services Web; une seule demande définit les données dont vous avez besoin et la façon dont vous souhaitez qu'elles soient renvoyées.

GraphQL résout bon nombre des défis posés par les API RESTful. Cela dit, peu d'entreprises ont des problèmes comparables à Facebook. Cela vaut la peine d'envisager GraphQL une fois que votre API RESTful a évolué au-delà de son simple point de départ.

Il existe de nombreux outils pour aider au développement de l'API RESTful dans tous les langages. Les options notables incluent:

  • Swagger : une variété d'outils pour aider à concevoir, documenter, simuler, tester et surveiller les API REST
  • Postman : une application de test d'API RESTful
  • Postwoman : une alternative open-source basée sur le Web à Postman.

Il existe également de nombreuses API REST publiques pour les blagues, la conversion de devises, le géocodage , les données gouvernementales et tous les sujets auxquels vous pouvez penser. Beaucoup sont gratuits, bien que certains vous obligent à vous inscrire pour une clé API ou à utiliser d'autres méthodes d'authentification. Les listes classées comprennent:

Essayez de consommer quelques API RESTful dans vos propres projets avant d'implémenter vos propres services Web.






Source link