Conception orientée ressources

L'objectif de ce guide de conception est d'aider les développeurs à concevoir des API en réseau simples, cohérentes et faciles à utiliser. En parallèle, elle 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 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 remporté un franc succès. En 2010, environ 74 % des API réseau publiques étaient des API REST HTTP (ou de type REST), la plupart utilisant JSON comme format de transmission.

Bien que les API HTTP/JSON soient très populaires sur Internet, la quantité de trafic qu'elles diffusent est inférieure à celle des API RPC traditionnelles. Par exemple, aux États-Unis, aux heures de pointe, environ la moitié du trafic Internet est constitué de contenu vidéo, 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 acheminer 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 pour les API HTTP/JSON publiques.

En réalité, les API RPC et les API HTTP/JSON sont nécessaires pour plusieurs raisons. Idéalement, une plate-forme d'API devrait 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.

Remarque : Ce guide de conception explique comment appliquer les principes REST aux conceptions d'API indépendamment du langage de programmation, du système d'exploitation ou du protocole réseau. Ce guide n'est PAS exclusivement dédié à la création d'API REST.

Qu'est-ce qu'une API REST ?

Une API REST est modélisée sous la forme de collections de ressources adressables individuellement (les noms de l'API). Les ressources sont référencées avec leurs noms de ressources et manipulées via un petit ensemble de méthodes (également appelées verbes ou opérations).

Les méthodes standards des API Google REST (également appelées Méthodes REST) sont List, Get, Create, Update, et Delete. Les méthodes personnalisées (également appelées verbes personnalisés ou opérations personnalisées) sont également à la disposition des concepteurs d'API pour une fonctionnalité qui n'est pas facilement mise en correspondance avec l'une des méthodes standards, telles que les transactions de base de données.

Remarque : Les verbes personnalisés ne signifient pas que des verbes HTTP personnalisés sont créés pour être compatibles avec les méthodes personnalisées. Pour les API basées sur HTTP, les mises en correspondance concernent uniquement les verbes HTTP les plus appropriés.

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 ressource est généralement modélisée comme une hiérarchie de ressources, chaque nœud étant soit une ressource simple, soit 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.

Examples

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/*.

Remarque :D'autres implémentations de l'API Pub/Sub peuvent choisir des schémas d'attribution de noms de ressources différents.

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 dispose des 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/*.
    • Une collection de sessions : projects/*/instances/*/databases/*/sessions/*.