Conception orientée ressources

L'objectif de ce guide de conception est d'aider les développeurs à concevoir des API réseau simples, cohérentes et faciles à utiliser. Parallèlement, il facilite également la convergence des conceptions d’API RPC basées sur des sockets avec des API REST basées sur HTTP.

Les API RPC sont souvent conçues en termes d'interfaces et de méthodes. Au fur et à mesure que des API RPC sont ajoutées, le résultat final peut être une surface API accablante et source de confusion, car les développeurs doivent apprendre chaque méthode individuellement. Évidemment, cela est à la fois chronophage et source d'erreurs.

Le style d'architecture de REST a été introduit et conçu principalement pour fonctionner correctement avec HTTP/1.1, mais également pour aider à résoudre ce problème. Son principe de base est de définir des ressources nommées pouvant être manipulées à l’aide d’un petit nombre de méthodes. Les ressources et les méthodes correspondent aux noms et aux verbes des API. Avec le protocole HTTP, les noms de ressources sont naturellement mis en correspondance avec des URL et les méthodes avec des méthodes HTTP POST, GET, PUT, PATCH et DELETE. Il en résulte beaucoup moins de choses à apprendre, car les développeurs peuvent se concentrer sur les ressources et leur relation, et supposer qu'ils disposent du même nombre réduit de méthodes standards.

Sur Internet, les API REST HTTP ont rencontré un énorme succès. En 2010, environ 74 % des API réseau publiques étaient des API HTTP REST (ou de type REST), la plupart utilisant JSON comme format de communication.

Bien que les API HTTP/JSON soient très populaires sur Internet, leur trafic est inférieur à celui des API RPC traditionnelles. Par exemple, aux États-Unis, environ la moitié du trafic Internet atteint son apogée lors des pics de trafic, et peu de personnes envisageraient d'utiliser des API HTTP/JSON pour diffuser ce type de contenu pour des raisons évidentes de performances. Dans les centres de données, de nombreuses entreprises utilisent des API RPC basées sur des sockets pour transporter la majeure partie du trafic réseau, ce qui peut impliquer des ordres de grandeur supérieurs de données (mesurés en octets) que les API HTTP/JSON publiques.

En réalité, les API RPC et les API HTTP/JSON sont nécessaires pour diverses raisons. Idéalement, une plate-forme d'API doit offrir une compatibilité optimale avec tous les types d'API. Ce guide de conception vous aide à concevoir et à créer des API conformes à ce principe. Pour cela, il applique les principes de conception axés sur les ressources à la conception générale d’API et définit de nombreux modèles de conception courants afin de faciliter l'utilisation et de réduire la complexité des API.

Qu'est-ce qu'une API REST ?

Une API REST est modélisée en tant que collections de ressources adressables individuellement (les noms de l'API). Les ressources sont référencées par leursnoms de ressources et manipulés via un petit ensemble deméthodes (également appeléverbes ou le ciblage paropérations applicables).

Les méthodes standards des API REST Google (également appelées méthodes REST) sont List, Get, Create et Update. et Delete. Les méthodes personnalisées (également appelées verbes personnalisés ou opérations personnalisées) sont également disponibles pour les concepteurs d'API pour les fonctionnalités qui ne Ils peuvent être mappés facilement à l'une des méthodes standards, telles que les transactions de base de données.

Flux de conception

Le guide de conception suggère de suivre les étapes suivantes lors de la conception d'API orientées ressources (des détails supplémentaires sont fournis dans les sections spécifiques ci-dessous) :

  • Déterminez les types de ressources fournies par une API.
  • Déterminez les relations entre les ressources.
  • Décidez des schémas de noms de ressources en fonction des types et des relations.
  • Décidez des schémas de ressources.
  • Joignez un ensemble minimal de méthodes aux ressources.

Ressources

Une API orientée ressources est généralement modélisée sous la forme d'une hiérarchie de ressources, où chaque nœud est une ressource simple ou une ressource de collection. Pour plus de commodité, ils sont souvent appelés respectivement "ressource" et "collection".

  • Une collection contient une liste de ressources du même type. Par exemple, un utilisateur possède une collection de contacts.
  • Une ressource possède un état et zéro ou plus sous-ressources. Chaque sous-ressource peut être une ressource simple ou une ressource de collection.

Par exemple, l'API Gmail contient un ensemble d'utilisateurs, chaque utilisateur disposant d'un ensemble de messages, d'une collection de fils de discussion, d'une collection de libellés, d'une ressource de profil et de plusieurs ressources de paramètres.

Bien qu'il existe un certain alignement conceptuel entre les systèmes de stockage et les API REST, un service avec une API orientée ressources n'est pas nécessairement une base de données. Il offre une grande flexibilité dans la façon dont il interprète les ressources et les méthodes. Par exemple, la création d'un événement de calendrier (ressource) peut créer des événements supplémentaires pour les participants, envoyer des invitations par e-mail aux participants, réserver des salles de conférence et mettre à jour les horaires de conférence vidéo.

Méthodes

La caractéristique principale d'une API orientée ressource est qu'elle met l'accent sur les ressources (modèle de données) par rapport aux méthodes effectuées sur les ressources (fonctionnalité). Une API type orientée ressource expose un grand nombre de ressources avec un petit nombre de méthodes. Les méthodes peuvent être des méthodes standards ou des méthodes personnalisées. Pour ce guide, les méthodes standards sont les suivantes : List, Get, Create, Update et Delete.

Lorsque la fonctionnalité de l'API correspond naturellement à l'une des méthodes standards, cette méthode doit être utilisée dans la conception de l'API. Pour les fonctionnalités qui ne correspondent pas naturellement à l'une des méthodes standards, des méthodes personnalisées peuvent être utilisées. Les méthodes personnalisées offrent la même liberté de conception que les API RPC traditionnelles, qui peuvent être utilisées pour mettre en œuvre des modèles de programmation courants, tels que les transactions de base de données ou l'analyse de données.

Exemples

Les sections suivantes présentent quelques exemples concrets sur la manière d'appliquer une conception d'API orientée ressources à des services à grande échelle. Vous trouverez plus d'exemples dans le dépôt des API Google.

Dans ces exemples, l'astérisque indique une ressource spécifique de la liste.

API Gmail

Le service de l'API Gmail met en œuvre l'API Gmail et expose la plupart des fonctionnalités de Gmail. Il expose le modèle de ressource suivant :

  • Service d'API : gmail.googleapis.com
    • Une collection d'utilisateurs : users/*. Chaque utilisateur dispose des ressources suivantes.
      • Une collection de messages : users/*/messages/*.
      • Une collection de fils de threads : users/*/threads/*.
      • Une collection de libellés : users/*/labels/*.
      • Une collection d'historiques des modifications : users/*/history/*.
      • Une ressource représentant le profil utilisateur : users/*/profile.
      • Une ressource représentant les paramètres utilisateur : users/*/settings.

API Cloud Pub/Sub

Le service pubsub.googleapis.com met en œuvre l'API Cloud Pub/Sub, qui définit le modèle de ressource suivant :

  • Service d'API : pubsub.googleapis.com
    • Une collection de sujets : projects/*/topics/*.
    • Une collection d'abonnements : projects/*/subscriptions/*.

API Cloud Spanner

Le service spanner.googleapis.com met en œuvre l'API Cloud Spanner, qui définit le modèle de ressource suivant :

  • Service d'API : spanner.googleapis.com
    • Une collection d'instances: projects/*/instances/*. Chaque instance possède les ressources suivantes :
    • Une collection d'opérations: projects/*/instances/*/operations/*.
    • Une collection de bases de données : projects/*/instances/*/databases/*. Chaque base de données dispose des ressources suivantes :
      • Une collection d'opérations : projects/*/instances/*/databases/*/operations/*.
      • Un ensemble de sessions : projects/*/instances/*/databases/*/sessions/*.