Conventions de nommage

Afin de fournir une expérience cohérente aux développeurs sur de nombreuses API et pour une période durable, tous les noms utilisés par une API devraient être :

  • simples
  • intuitifs
  • cohérents

Cela inclut les noms d'interfaces, de ressources, de collections, de méthodes et de messages.

Étant donné que de nombreux développeurs ne sont pas anglophones, l'un des objectifs de ces conventions d'attribution de noms est de permettre à la majorité des développeurs de comprendre facilement une API. Pour cela, il est conseillé d'utiliser un vocabulaire simple, cohérent et réduit lors de la désignation des méthodes et des ressources.

  • Les noms utilisés dans les API devraient être en anglais américain correct. Par exemple, "license" (au lieu de "licence"), "color" (au lieu de "colour").
  • Des formes abrégées communément acceptées ou des abréviations de mots longs peuvent être utilisées par souci de concision. Par exemple, "API" est préférable à "Application Programming Interface".
  • Dans la mesure du possible, utilisez une terminologie intuitive et familière. Par exemple, lorsque vous décrivez la suppression (et la destruction) d'une ressource, le terme "delete" est préférable au terme "erase".
  • Utilisez le même nom ou le même terme pour le même concept, y compris pour les concepts partagés par plusieurs API.
  • Évitez de surcharger un nom. Utilisez des noms différents pour des concepts différents.
  • Évitez les noms trop généraux qui sont ambigus dans le contexte de l'API et de l'écosystème plus large des API Google. Ils peuvent entraîner une mauvaise compréhension des concepts de l'API. Choisissez plutôt des noms spécifiques qui décrivent avec précision le concept d'API. Cela est particulièrement important pour les noms qui définissent des éléments d'API de premier ordre, tels que des ressources. Il n’existe pas de liste définitive de noms à éviter, car chaque nom doit être évalué dans le contexte d’autres noms. "Instance", "info" et "service" sont des exemples de noms qui ont posé problème par le passé. Les noms choisis doivent décrire clairement le concept de l'API (par exemple, répondre à la question "instance de quoi ?") et établir une distinction avec d'autres concepts pertinents (par exemple, "alerte" renvoie-t-il à la règle, au signal ou à la notification ?).
  • Réfléchissez bien à l'utilisation de noms qui pourraient entrer en conflit avec des mots clés dans les langages de programmation courants. Ces noms peuvent être utilisés, mais déclencheront probablement un contrôle plus approfondi lors de l'examen de l'API. Utilisez-les judicieusement et avec parcimonie.

Noms de produit

Les noms de produit font référence aux noms marketing des API, tels qu'API Google Agenda. Ils doivent être systématiquement utilisés pour les API, les interfaces utilisateur, la documentation, les conditions d'utilisation, les relevés de compte, les contrats commerciaux, etc. Les API Google doivent utiliser des noms de produit approuvés par les équipes produit et marketing.

Le tableau ci-dessous montre des exemples de tous les noms d'API associés et de leur cohérence. Poursuivez la lecture de cette page pour plus d'informations sur les noms respectifs et leurs conventions.

Nom d'API Exemple
Nom du produit Google Calendar API
Nom du service calendar.googleapis.com
Nom du package google.calendar.v3
Nom d'interface google.calendar.v3.CalendarService
Répertoire source //google/calendar/v3
Nom d'API calendar

Noms de service

Les noms de service devraient être des noms DNS valides du point de vue de la syntaxe (conformément au protocole RFC 1035), qui peuvent être résolus en une ou plusieurs adresses réseau. Les noms de service des API Google publiques suivent le modèle xxx.googleapis.com. Par exemple, le nom de service de Google Agenda est calendar.googleapis.com.

Si une API est composée de plusieurs services, vous devriez les nommer de manière à faciliter leur visibilité. Pour cela, vous pouvez par exemple partager un préfixe commun à tous les noms de service. Par exemple, les services build.googleapis.com et buildresults.googleapis.com sont tous deux des services qui font partie de l'API Google Build.

Noms des packages

Les noms de package déclarés dans les fichiers .proto de l'API devraient être cohérents avec les noms de produit et les noms de service. Les noms de package devraient utiliser des noms de composants au singulier pour éviter le mélange de noms de composants au singulier et au pluriel. Les noms de packages ne doivent pas contenir de traits de soulignement. Les noms de package pour les API avec versions gérées doivent se terminer par la version. Exemple :

// Google Calendar API
package google.calendar.v3;

Une API extraite qui n'est pas directement associée à un service, telle que l'API Google Watcher, devrait utiliser des noms de package proto cohérents avec le nom du produit :

// Google Watcher API
package google.watcher.v1;

Les noms de package Java spécifiés dans les fichiers .proto de l'API doivent correspondre aux noms de package proto avec le préfixe de nom de package Java standard (com., edu., net., etc.). Exemple :

package google.calendar.v3;

// Specifies Java package name, using the standard prefix "com."
option java_package = "com.google.calendar.v3";

ID de collection

Les ID de collection doivent utiliser le pluriel et lowerCamelCase, ainsi que l'orthographe et la sémantique de l'anglais américain. Par exemple : events, children ou deletedEvents.

Noms d'interface

Pour éviter toute confusion avec les noms de service tels que pubsub.googleapis.com, le terme nom d'interface fait référence au nom utilisé lors de la définition d'un service dans un fichier .proto :

// Library is the interface name.
service Library {
  rpc ListBooks(...) returns (...);
  rpc ...
}

Vous pouvez considérer le nom du service comme une référence à la mise en œuvre réelle d'un ensemble d'API, tandis que le nom d'interface fait référence à la définition abstraite d'une API.

Un nom d'interface devrait utiliser un nom intuitif tel que "Calendar" ou "Blob". Le nom ne devrait pas entrer en conflit avec des concepts bien établis dans les langages de programmation et leurs bibliothèques d'exécution (par exemple, "File").

Dans les rares cas où un nom d'interface entrerait en conflit avec un autre nom au sein de l'API, un suffixe (par exemple, Api ou Service) devrait être utilisé pour lever l'ambiguïté.

Noms de méthode

Un service peut, dans sa spécification IDL, définir une ou plusieurs méthodes RPC correspondant à des méthodes sur des collections et des ressources. Les noms de méthode doivent respecter la convention d'attribution de noms de VerbNoun en camel case et en majuscules, où le nom est généralement le type de ressource.

Verbe Nom Nom de la méthode Message de requête Message de réponse
List Book ListBooks ListBooksRequest ListBooksResponse
Get Book GetBook GetBookRequest Book
Create Book CreateBook CreateBookRequest Book
Update Book UpdateBook UpdateBookRequest Book
Rename Book RenameBook RenameBookRequest RenameBookResponse
Delete Book DeleteBook DeleteBookRequest google.protobuf.Empty

La partie verbale du nom de la méthode devrait utiliser l'impératif pour les ordres ou les commandes, plutôt que l'indicatif, réservé aux questions.

Pour les méthodes standards, la partie nominale du nom de la méthode doit être au singulier pour toutes les méthodes, à l'exception de List, et doit être au pluriel pour List. Pour les méthodes personnalisées, le nom peut être au singulier ou au pluriel selon les besoins. Les méthodes de traitement par lot doivent utiliser le nom au pluriel.

Cet usage peut facilement introduire de la confusion lorsque le verbe pose une question sur une sous-ressource dans l'API, pour laquelle on utilise souvent l'indicatif. Par exemple, pour ordonner à l'API de créer un livre, la méthode CreateBook (à l'impératif) est clairement celle à utiliser, mais pour interroger l'API sur l'état de l'éditeur de l'ouvrage, l'indicatif serait préférable : par exemple IsBookPublisherApproved ou NeedsPublisherApproval. Pour rester à l'impératif dans de telles situations, utilisez des commandes telles que "check" (CheckBookPublisherApproved) et "validate" (ValidateBookPublisher).

Les noms de méthodes ne devraient pas inclure de prépositions (par exemple, "For", "With", "At", "To"). En règle générale, les noms de méthode avec prépositions indiquent qu'une nouvelle méthode est utilisée. Un champ devrait plutôt être ajouté à une méthode existante, ou la méthode devrait utiliser un verbe distinct.

Par exemple, si un message CreateBook existe déjà et que vous envisagez d'ajouter CreateBookFromDictation, optez plutôt pour une méthode TranscribeBook.

Noms de messages

Les noms des messages doivent être courts et concis. Évitez les mots inutiles ou redondants. Les adjectifs peuvent souvent être omis s'il n'y a pas de message correspondant sans l'adjectif. Par exemple, l'adjectif Shared dans SharedProxySettings n'est pas nécessaire s'il n'existe aucun paramètre de proxy unshared (non partagé).

Les noms des messages ne devraient pas inclure de prépositions (par exemple, "With", "For"). En règle générale, les noms de message contenant des prépositions seraient mieux représentés avec des champs facultatifs sur le message.

Messages de requête et de réponse

Les messages de requête et de réponse des méthodes RPC devraient porter le nom des méthodes avec les suffixes Request et Response, sauf si le type de requête ou de réponse de méthode est :

  • un message vide (utilisez google.protobuf.Empty) ;
  • un type de ressource, ou ;
  • une ressource représentant une opération.

Cela s'applique généralement aux requêtes ou aux réponses utilisées dans les méthodes standards Get, Create, Update ou Delete.

Noms d'énumération

Les types des énumérations doivent utiliser des noms en majuscule et camel case.

Les valeurs d'énumération doivent utiliser des NOMS_EN_MAJUSCULES_AVEC_TRAITS_DE_SOULIGNEMENT. Chaque valeur d'énumération doit se terminer par un point-virgule, et non par une virgule. La première valeur devrait être nommée ENUM_TYPE_UNSPECIFIED (type d'énumération non spécifiée), car elle est renvoyée lorsqu'une valeur d'énumération n'est pas explicitement spécifiée.

enum FooBar {
  // The first value represents the default and must be == 0.
  FOO_BAR_UNSPECIFIED = 0;
  FIRST_VALUE = 1;
  SECOND_VALUE = 2;
}

Wrappers

Les messages encapsulant des types d'énumération proto2 pour lesquels la valeur 0 a une signification autre que UNSPECIFIED devraient être nommés avec le suffixe Value et comporter un seul champ nommé value.

enum OldEnum {
  VALID = 0;
  OTHER_VALID = 1;
}
message OldEnumValue {
  OldEnum value = 1;
}

Noms de champs

Les définitions de champ dans les fichiers .proto doivent utiliser des noms_en_minuscules_séparés_par_des_tirets_bas. Ces noms seront mis en correspondance avec la convention d'attribution de noms native dans le code généré pour chaque langage de programmation.

Les noms de champs ne devraient pas inclure de prépositions (par exemple "for", "during", "at") :

  • reason_for_error devrait plutôt être error_reason.
  • cpu_usage_at_time_of_failure devrait plutôt être failure_time_cpu_usage.

Les noms de champs ne devraient pas utiliser d'adjectifs postpositifs (modificateurs placés après le nom). Par exemple :

  • items_collected devrait plutôt être collected_items.
  • objects_imported devrait plutôt être imported_objects.

Noms de champs répétés

Les champs répétés dans les API doivent utiliser des formes appropriées au pluriel. Cela correspond à la convention des API Google existantes et aux attentes courantes des développeurs externes.

Temps et durée

Pour représenter un moment précis indépendant de tout fuseau horaire ou de tout calendrier, google.protobuf.Timestamp doit être utilisé, et le nom de champ doit se terminer par time, par exemple start_time et end_time.

Si l'heure correspond à une activité, le nom du champ doit se présenter sous la forme verb_time, par exemple create_time, update_time. Évitez d'utiliser un verbe au passé, tel que created_time ou last_updated_time.

Pour représenter le délai entre deux moments indépendants de tout calendrier ou concept tel que "jour" ou "mois", google.protobuf.Duration doit être utilisé.

message FlightRecord {
  google.protobuf.Timestamp takeoff_time = 1;
  google.protobuf.Duration flight_duration = 2;
}

Si vous devez représenter des champs liés à l'heure à l'aide d'un type entier pour des raisons d'héritage ou de compatibilité, y compris l'heure de l'horloge murale, la durée, le délai et le temps d'attente, les noms de champs doivent avoir la forme suivante :

xxx_{time|duration|delay|latency}_{seconds|millis|micros|nanos}

message Email {
  int64 send_time_millis = 1;
  int64 receive_time_millis = 2;
}

Si vous devez représenter l'horodatage à l'aide d'un type de chaîne pour des raisons d'héritage ou de compatibilité, les noms de champ ne devraient pas inclure de suffixe d'unité. La représentation sous forme de chaîne doit utiliser le format RFC 3339, par exemple "2014-07-30T10:43:17Z".

Date et heure du jour

Pour les dates qui sont indépendantes du fuseau horaire et de l'heure de la journée, google.type.Date doit être utilisé avec le suffixe _date. Si une date doit être représentée sous forme de chaîne, elle devrait être au format de date ISO 8601 AAAA-MM-JJ, par exemple 2014-07-30.

Pour les heures de la journée indépendantes du fuseau horaire et de la date, google.type.TimeOfDay devrait être utilisé avec le suffixe _time. Si une heure de la journée doit être représentée sous forme de chaîne, elle doit être au format 24 heures ISO 8601 HH:MM:SS [.FFF], par exemple 14:55:01.672.

message StoreOpening {
  google.type.Date opening_date = 1;
  google.type.TimeOfDay opening_time = 2;
}

Quantités

Les quantités représentées par un type entier doivent inclure l'unité de mesure.

xxx_{bytes|width_pixels|meters}

Si la quantité est un nombre d'éléments, le champ doit comporter le suffixe _count, par exemple node_count.

Champ de filtre de List

Si une API est compatible avec le filtrage des ressources renvoyées par la méthode List, le champ contenant l'expression de filtre doit être nommé filter. Exemple :

message ListBooksRequest {
  // The parent resource name.
  string parent = 1;

  // The filter expression.
  string filter = 2;
}

Réponse de List

Le nom du champ dans le message de réponse de la méthode List, qui contient la liste des ressources doit être le nom de la ressource en question au pluriel. Par exemple, une méthode CalendarApi.ListEvents() doit définir un message de réponse ListEventsResponse avec un champ répété appelé events pour la liste des ressources renvoyées.

service CalendarApi {
  rpc ListEvents(ListEventsRequest) returns (ListEventsResponse) {
    option (google.api.http) = {
      get: "/v3/{parent=calendars/*}/events";
    };
  }
}

message ListEventsRequest {
  string parent = 1;
  int32 page_size = 2;
  string page_token = 3;
}

message ListEventsResponse {
  repeated Event events = 1;
  string next_page_token = 2;
}

Camel case

À l'exception des noms de champs et des valeurs d'énumération, toutes les définitions des fichiers .proto doivent utiliser des noms en camel case et en majuscules, tels que définis par le style Java de Google.

Abréviation de noms

Pour les abréviations de noms bien connues des développeurs de logiciels, telles que config et spec, les abréviations doivent être préférées aux appellations longues dans les définitions d'API. Ainsi, le code source sera facile à lire et à écrire. Dans les documentations officielles, les mots entiers devraient être utilisés. Exemples :

  • config (configuration)
  • id (identifier)
  • spec (specification)
  • stat (statistics)
Précédent
Erreurs
Suivant
Modèles de conception