Noms de ressources

Dans les API orientées ressources, les ressources sont des entités nommées et les noms de ressources sont leurs identifiants. Chaque ressource doit avoir son propre nom de ressource unique. Le nom de la ressource est composé de l'ID de la ressource elle-même, des ID de toutes les ressources parentes et de son nom de service d'API. Nous examinerons les ID de ressource et la manière dont un nom de ressource est créé ci-dessous.

Les API gRPC doivent utiliser des URI sans schéma pour les noms de ressources. Elles suivent généralement les conventions de l'URL REST et se comportent presque comme des chemins d'accès de fichiers en réseau. Elles peuvent facilement être mappées vers des URL REST : pour plus d'informations, consultez la section Méthodes standards.

Une collection est un type spécial de ressource qui contient une liste de sous-ressources de même type. Par exemple, un répertoire est une collection de ressources de fichiers. L'ID de ressource pour une collection s'appelle ID de collection.

Le nom de la ressource est organisé hiérarchiquement à l'aide des ID de collection et de ressource, séparés par des barres obliques. Si une ressource contient une sous-ressource, le nom de la sous-ressource est formé en spécifiant le nom de la ressource parente suivi de l'ID de la sous-ressource, encore une fois, séparés par des barres obliques.

Exemple 1 : Un service de stockage possède une collection d'éléments buckets, où chaque bucket contient une collection d'éléments objects :

Nom de service de l'API	ID de collection	ID de ressource	ID de collection	ID de ressource
//storage.googleapis.com	/buckets	/bucket-id	/objects	/object-id

Exemple 2 : Un service de messagerie possède une collection d'éléments users. Chaque utilisateur possède une sous-ressource settings et la sous-ressource settings possède un certain nombre d'autres sous-ressources, y compris customFrom :

Nom de service de l'API	ID de collection	ID de ressource	ID de ressource	ID de ressource
//mail.googleapis.com	/users	/name@example.com	/settings	/customFrom

Un producteur d'API peut choisir n'importe quelle valeur acceptable pour les ID de ressource et de collection tant qu'ils sont uniques dans la hiérarchie des ressources. Vous pouvez trouver plus de consignes ci-dessous pour choisir des ID de ressources et de collections appropriés.

En scindant le nom de la ressource, tel que name.split("/")[n], vous pouvez obtenir les ID de collection et de ressource individuels, en supposant qu'aucun des segments ne contient de barre oblique.

Nom complet de ressource

Un URI sans schéma composé d'un nom de service d'API compatible avec DNS et d'un chemin d'accès à la ressource. Le chemin d'accès à la ressource est également appelé nom de ressource relatif. Exemple :

"//library.googleapis.com/shelves/shelf1/books/book2"

Le nom de service d'API permet aux clients de localiser le point de terminaison du service d'API. Il peut s'agir d'un faux nom DNS réservé aux services internes. Lorsque le nom du service de l'API est évident en contexte, des noms de ressources relatifs sont souvent utilisés.

Nom de ressource relatif

Un chemin d'accès d'URI (path-noscheme) sans le symbole "/" initial. Il identifie une ressource dans le service d'API. Exemple :

"shelves/shelf1/books/book2"

ID de ressource

Un ID de ressource se compose généralement d'un ou de plusieurs segments d'URI non vides (segment-nz-nc) qui identifient la ressource dans sa ressource parente. Consultez les exemples ci-dessus. L'ID de ressource non-final dans un nom de ressource doit avoir exactement un segment d'URL, tandis que l'ID de ressource de fin dans un nom de ressource peut avoir plusieurs segments d'URI. Exemple :

ID de collection	ID de ressource
files	source/py/parser.py

Les services d'API doivent utiliser des identifiants de ressources compatibles avec les URL lorsque cela est possible. Les ID de ressources doivent être clairement documentés, qu'ils soient attribués par le client ou le serveur. Par exemple, les noms de fichier sont généralement attribués par les clients, tandis que les ID d'e-mail le sont généralement par les serveurs.

ID de collection

Un segment d'URI non vide (segment-nz-nc) identifiant la ressource de collection dans sa ressource parente, voir les exemples ci-dessus.

Étant donné que les ID de collection apparaissent souvent dans les bibliothèques clientes générées, ils doivent être conformes aux exigences suivantes :

Ils doivent être des identifiants C/C++ valides.
Ils doivent être au pluriel et en lower camel case. Si le terme n'a pas de forme appropriée au pluriel, comme "temps", le singulier doit être utilisé.
Ils doivent utiliser des termes clairs et concis.
Les termes trop génériques doivent être évités ou qualifiés. Par exemple, rowValues est préférable à values. Les termes suivants doivent être évités sans réserve :
- Éléments
- Entrées
- Instances
- Articles
- Objets
- Ressources
- Types
- Valeurs

Nom de ressource ou URL

Bien que les noms de ressources complets ressemblent à des URL normales, il ne s'agit pas de la même chose. Une seule ressource peut être exposée par différentes versions d'API, et différents protocoles d'API ou points de terminaison de réseau d'API. Le nom complet de la ressource ne spécifie pas ces informations. Il doit donc être mappé vers une version et un protocole d'API spécifiques pour pouvoir être utilisé.

Pour utiliser un nom de ressource complet via les API REST, vous devez le convertir en une URL REST en ajoutant le schéma HTTPS avant le nom du service, en ajoutant la version majeure de l'API avant le chemin d'accès à la ressource et en échappant le chemin d'accès à la ressource de l'URL. Exemple :

// This is a calendar event resource name.
"//calendar.googleapis.com/users/john smith/events/123"

// This is the corresponding HTTP URL.
"https://calendar.googleapis.com/v3/users/john%20smith/events/123"

Nom de ressource en tant que chaîne

Les API Google doivent représenter les noms de ressources à l'aide de chaînes de base, sauf en cas de problème de rétrocompatibilité. Les noms de ressources doivent être gérés de la même manière que les chemins d'accès de fichiers normaux. Lorsqu'un nom de ressource est transmis entre différents composants, il doit être traité comme une valeur atomique et ne présenter aucune perte de données.

Pour les définitions de ressources, le premier champ doit être un champ de chaîne pour le nom de ressource, et doit être appelé name.

Exemple :

service LibraryService {
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
      get: "/v1/{name=shelves/*/books/*}"
    };
  };
  rpc CreateBook(CreateBookRequest) returns (Book) {
    option (google.api.http) = {
      post: "/v1/{parent=shelves/*}/books"
      body: "book"
    };
  };
}

message Book {
  // Resource name of the book. It must have the format of "shelves/*/books/*".
  // For example: "shelves/shelf1/books/book2".
  string name = 1;

  // ... other properties
}

message GetBookRequest {
  // Resource name of a book. For example: "shelves/shelf1/books/book2".
  string name = 1;
}

message CreateBookRequest {
  // Resource name of the parent resource where to create the book.
  // For example: "shelves/shelf1".
  string parent = 1;
  // The Book resource to be created. Client must not set the `Book.name` field.
  Book book = 2;
}

Remarque : Pour assurer la cohérence des noms de ressources, la barre oblique avant ne doit pas être capturée par une variable de modèle d'URL. Par exemple, le modèle d'URL "/v1/{name=shelves/*/books/*}" doit être utilisé au lieu de "/v1{name=/shelves/*/books/*}".

Questions

Q : Pourquoi ne pas utiliser les identifiants de ressources pour identifier une ressource ?

Pour tout système de grande taille, il existe de nombreux types de ressources. Pour identifier une ressource à l'aide des ID de ressources, nous utilisons un tuple spécifique à la ressource, tel que (bucket, object) ou (user, album, photo). Cela entraîne plusieurs problèmes majeurs :

Les développeurs doivent comprendre et se souvenir de tels tuples anonymes.
La transmission des tuples est généralement plus difficile que celle de chaînes.
Les infrastructures centralisées, telles que les systèmes de journalisation et de contrôle d'accès ne comprennent pas les tuples spécialisés.
Les tuples spécialisés limitent la flexibilité de conception d'une API, par exemple en fournissant des interfaces d'API réutilisables. Ainsi, les opérations de longue durée peuvent fonctionner avec de nombreuses autres interfaces d'API car elles utilisent des noms de ressources flexibles.

Q : Pourquoi le champ de nom de ressource est-il nommé `name` au lieu de `id` ?

Le champ du nom de la ressource est nommé comme le concept de ressource "nom". De manière générale, nous trouvons que le concept de name (nom) est source de confusion pour les développeurs. Par exemple, un nom de fichier est-il vraiment juste le nom ou le chemin d'accès complet ? En réservant le champ standard name, les développeurs sont contraints de choisir un terme plus approprié, tel que display_name, title ou full_name.

Q : Comment générer et analyser les noms de ressources ?

Les noms de ressources se comportent comme des chemins d'accès aux fichiers. Vous pouvez utiliser printf() pour générer des noms de ressources à partir d'ID de ressources. Vous pouvez utiliser split() pour analyser les noms de ressources dans les identifiants de ressources. Notez que certains ID de ressource de fin peuvent comporter plusieurs segments d'URI séparés par /, comme un chemin d'accès au fichier.

Conception orientée ressources

Méthodes standards