Convenzioni di denominazione

Per offrire un'esperienza coerente per gli sviluppatori in molte API e su un lungo periodo di tempo, tutti i nomi utilizzati da un'API devono essere:

  • semplice
  • intuitivo
  • coerente

Sono inclusi i nomi di interfacce, risorse, raccolte, metodi e messaggi.

Poiché molti sviluppatori non parlano inglese come lingua madre, uno scopo di queste convenzioni di denominazione è garantire che la maggior parte degli sviluppatori possa comprendere facilmente un'API. A tal fine, incoraggia l'uso di un vocabolario semplice, coerente e ridotto per la denominazione di metodi e risorse.

  • I nomi utilizzati nelle API devono essere in inglese americano corretto. Ad esempio, licenza (anziché licenza), colore (anziché colore).
  • Per brevità, possono essere utilizzate forme brevi o abbreviazioni di parole lunghe comunemente accettate. Ad esempio, è preferibile utilizzare API anziché Application Programming Interface.
  • Se possibile, utilizza una terminologia intuitiva e familiare. Ad esempio, quando si descrive la rimozione (e l'eliminazione) di una risorsa, è preferibile eliminare rispetto a cancellare.
  • Utilizza lo stesso nome o termine per lo stesso concetto, inclusi i concetti condivisi tra le API.
  • Evita la sovraccarica di nomi. Utilizza nomi diversi per concetti diversi.
  • Evita nomi troppo generici e ambigui nel contesto dell'API e dell'ecosistema più ampio delle API Google. Possono portare a misunderstandinġ dei concetti relativi alle API. Scegli invece nomi specifici che descrivano con precisione il concetto dell'API. Ciò è particolarmente importante per i nomi che definiscono elementi API di primo ordine, come le risorse. Non esiste un elenco definitivo di nomi da evitare, poiché ogni nome deve essere valutato nel contesto di altri nomi. Instance, info e service sono esempi di nomi che hanno creato problemi in passato. I nomi scelto devono descrivere chiaramente il concetto dell'API (ad esempio, istanza di cosa?) e distinguerlo da altri concetti pertinenti (ad esempio, "avviso" indica la regola, l'indicatore o la notifica?).
  • Valuta attentamente l'utilizzo di nomi che potrebbero entrare in conflitto con le parole chiave nei linguaggi di programmazione comuni. Questi nomi possono essere utilizzati, ma probabilmente attiveranno un'ulteriore verifica durante la revisione dell'API. Utilizzale con giudizio e parsimonia.

Nomi dei prodotti

I nomi dei prodotti fanno riferimento ai nomi di marketing dei prodotti delle API, ad esempio API Google Calendar. I nomi dei prodotti devono essere utilizzati in modo coerente da API, UI, documentazione, Termini di servizio, fatture, contratti commerciali e così via. Le API di Google devono utilizzare i nomi dei prodotti approvati dai team di prodotto e marketing.

La tabella seguente mostra esempi di tutti i nomi delle API correlate e la relativa consistenza. Continua a leggere questa pagina per ulteriori dettagli sui rispettivi nomi e sulle relative convenzioni.

Nome API Esempio
Nome prodotto Google Calendar API
Nome servizio calendar.googleapis.com
Nome pacchetto google.calendar.v3
Nome interfaccia google.calendar.v3.CalendarService
Directory di origine //google/calendar/v3
Nome API calendar

Nomi dei servizi

I nomi di servizio devono essere nomi DNS sintatticamente validi (come da RFC 1035) che possono essere risolti in uno o più indirizzi di rete. I nomi dei servizi delle API di Google pubbliche seguono il pattern: xxx.googleapis.com. Ad esempio, il nome del servizio di Google Calendar è calendar.googleapis.com.

Se un'API è composta da più servizi, devono essere denominati in modo da favorire la rilevabilità. Un modo per farlo è che i nomi dei servizi condividano un prefisso comune. Ad esempio, i servizi build.googleapis.com e buildresults.googleapis.com fanno entrambi parte dell'API Google Build.

Nomi pacchetto

I nomi dei pacchetti dichiarati nei file .proto dell'API devono essere coerenti con i nomi dei prodotti e dei servizi. I nomi dei pacchetti devono utilizzare nomi di componenti singolari per evitare di mescolare nomi di componenti singolari e plurali. I nomi dei pacchetti non devono utilizzare i trattini bassi. I nomi dei pacchetti per le API con versione devono terminare con la versione. Ad esempio:

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

Un'API astratta non associata direttamente a un servizio, come l'API Google Watcher, deve utilizzare nomi di pacchetti proto coerenti con il nome del prodotto:

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

I nomi dei pacchetti Java specificati nei file .proto dell'API devono corrispondere ai nomi dei pacchetti proto con il prefisso del nome del pacchetto Java standard (com.,edu., net. e così via). Ad esempio:

package google.calendar.v3;

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

ID raccolta

Gli ID raccolta devono utilizzare la forma plurale e lowerCamelCase, nonché la semantica e l'ortografia dell'inglese americano. Ad esempio: events, children o deletedEvents.

Nomi delle interfacce

Per evitare confusione con i nomi di servizio come pubsub.googleapis.com, il termine nome dell'interfaccia si riferisce al nome utilizzato per definire un service in un file .proto:

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

Puoi considerare il nome del servizio come un riferimento all'implementazione effettiva di un insieme di API, mentre il nome dell'interfaccia si riferisce alla definizione astratta di un'API.

Il nome di un'interfaccia deve utilizzare un sostantivo intuitivo come Calendar o Blob. Il nome non deve entrare in conflitto con concetti ben stabiliti nei linguaggi di programmazione e nelle relative librerie di runtime (ad esempio File).

Nei rari casi in cui un nome dell'interfaccia entri in conflitto con un altro nome all'interno dell'API, è obbligatorio utilizzare un suffisso (ad esempio Api o Service) per eliminare l'ambiguità.

Nomi dei metodi

Un servizio può, nella sua specifica IDL, definire uno o più metodi RPC corrispondenti ai metodi di raccolte e risorse. I nomi dei metodi devono seguire la convenzione di denominazione di VerbNoun in lettere maiuscole iniziali, dove il nome è in genere il tipo di risorsa.

Verbo Nome Nome metodo Messaggio di richiesta Messaggio di risposta
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 parte del verbo del nome del metodo deve utilizzare il modo imperativo, che è destinato a ordini o comandi, anziché il modo indicativo, che è destinato alle domande.

Per i metodi standard, la parte del nome del metodo che indica il nome deve essere al singolare per tutti i metodi tranne List e deve essere al plurale per List. Per i metodi personalizzati, il sostantivo può essere singolare o plurale, a seconda dei casi. I metodi batch devono utilizzare il nome plurale.

Questo può essere facilmente confuso quando il verbo pone una domanda su una risorsa secondaria nell'API, che spesso è espressa nel modo indicativo. Ad esempio, ordinare all'API di creare un libro è chiaramente CreateBook (nel modo imperativo), ma chiedere all'API lo stato dell'editore del libro potrebbe utilizzare il modo indicativo, ad esempio IsBookPublisherApproved o NeedsPublisherApproval. Per mantenere il modo imperativo in situazioni come questa, utilizza comandi come "controlla" (CheckBookPublisherApproved) e "convalida" (ValidateBookPublisher).

I nomi dei metodi non devono includere preposizioni (ad es. "Per", "Con", "A", "A"). In genere, i nomi dei metodi con preposizioni indicano che viene utilizzato un nuovo metodo dove invece dovrebbe essere aggiunto un campo a un metodo esistente o il metodo dovrebbe utilizzare un verbo distinto.

Ad esempio, se esiste già un messaggio CreateBook e stai valutando di aggiungere CreateBookFromDictation, valuta la possibilità di utilizzare un metodo TranscribeBook.

Nomi dei messaggi

I nomi dei messaggi devono essere brevi e concisi. Evita le parole inutili o ridondanti. Spesso gli aggettivi possono essere omessi se non esiste un messaggio corrispondente senza l'aggettivo. Ad esempio, Shared in SharedProxySettings è non necessario se non sono presenti impostazioni proxy non condivise.

I nomi dei messaggi non devono includere preposizioni (ad es. "Con", "Per"). In genere, i nomi dei messaggi con preposizioni sono meglio rappresentati con i campi facoltativi del messaggio.

Messaggi di richiesta e risposta

I messaggi di richiesta e risposta per i metodi RPC devono essere denominati in base ai nomi dei metodi con i suffissi Request e Response, rispettivamente, a meno che il tipo di richiesta o risposta del metodo non sia:

  • un messaggio vuoto (utilizza google.protobuf.Empty),
  • un tipo di risorsa oppure
  • una risorsa che rappresenta un'operazione

In genere, si applica alle richieste o alle risposte utilizzate nei metodi standard Get, Create, Update o Delete.

Nomi degli enum

I tipi di enum devono utilizzare nomi in maiuscolo CamelCase.

I valori dell'enum devono utilizzare CAPITALIZED_NAMES_WITH_UNDERSCORES. Ogni valore enumerato deve terminare con un punto e virgola, non con una virgola. Il primo valore deve essere denominato ENUM_TYPE_UNSPECIFIED, in quanto viene restituito quando un valore enumerato non è specificato esplicitamente.

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

Wrapper

I messaggi che incapsulano tipi di enum proto2 in cui il valore 0 ha un significato diverso da UNSPECIFIED devono essere denominati con il suffisso Value e avere un singolo campo denominato value.

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

Nomi dei campi

Le definizioni dei campi nei file .proto devono utilizzare nomi con lettere minuscole separati da trattini bassi. Questi nomi verranno mappati alla convenzione di denominazione nativa nel codice generato per ogni linguaggio di programmazione.

I nomi dei campi non devono includere preposizioni (ad es. "per", "durante", "a"), ad esempio:

  • reason_for_error dovrebbe essere error_reason
  • cpu_usage_at_time_of_failure dovrebbe essere failure_time_cpu_usage

I nomi dei campi non devono utilizzare aggettivi postpositivi (modificatori posti dopo il nome), ad esempio:

  • items_collected dovrebbe essere collected_items
  • objects_imported dovrebbe essere imported_objects

Nomi di campi ripetuti

I campi ripetuti nelle API devono utilizzare le forme plurali appropriate. Questo corrisponde alla convenzione delle API Google esistenti e alle aspettative comuni degli sviluppatori esterni.

Ora e durata

Per rappresentare un punto nel tempo indipendente da qualsiasi fuso orario o calendario, google.protobuf.Timestamp deve essere utilizzato e il nome del campo deve terminare con time, ad esempio start_time e end_time.

Se l'ora si riferisce a un'attività, il nome del campo deve avere la forma verb_time, ad esempio create_time, update_time. Evita di utilizzare il verbo al passato, ad esempio created_time o last_updated_time.

Per rappresentare un intervallo di tempo tra due punti indipendenti da qualsiasi calendario e da concetti come "giorno" o "mese", google.protobuf.Duration deve essere utilizzato.

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

Se devi rappresentare i campi relativi al tempo utilizzando un tipo intero per motivi di compatibilità o legacy, tra cui ora del giorno, durata, ritardo e latenza, i nomi dei campi devono avere il seguente formato:

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

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

Se devi rappresentare il timestamp utilizzando il tipo di stringa per motivi di compatibilità o legacy, i nomi dei campi non devono includere alcun suffisso di unità. La rappresentazione di stringa deve utilizzare il formato RFC 3339, ad es. "2014-07-30T10:43:17Z".

Data e ora del giorno

Per le date indipendenti dal fuso orario e dall'ora del giorno, google.type.Date deve essere utilizzato e deve avere il suffisso _date. Se una data deve essere rappresentata come stringa, deve essere nel formato data ISO 8601 AAAA-MM-GG, ad esempio 2014-07-30.

Per le ore del giorno indipendenti dal fuso orario e dalla data, deve essere utilizzato google.type.TimeOfDay e deve avere il suffisso _time. Se un'ora deve essere rappresentata come stringa, deve essere nel formato orario 24 ore ISO 8601 HH:MM:SS[.FFF], ad esempio 14:55:01.672.

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

Quantità

Le quantità rappresentate da un tipo di numero intero devono includere l'unità di misura.

xxx_{bytes|width_pixels|meters}

Se la quantità è un numero di articoli, il campo deve avere il suffisso _count, ad esempio node_count.

Campo filtro elenco

Se un'API supporta il filtro delle risorse restituite dal metodo List, il campo contenente l'espressione di filtro deve essere denominato filter. Ad esempio:

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

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

Risposta elenco

Il nome del campo nel messaggio di risposta del metodo List, che contiene l'elenco delle risorse, deve essere una forma plurale del nome della risorsa stessa. Ad esempio, un metodo CalendarApi.ListEvents() deve definire un messaggio di risposta ListEventsResponse con un campo ripetuto chiamato events per l'elenco delle risorse restituite.

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;
}

Notazione a cammello

Ad eccezione dei nomi dei campi e dei valori dell'enum, tutte le definizioni all'interno dei file .proto devono utilizzare nomi in maiuscolo CamelCase, come definito da Google Java Style.

Abbreviazione del nome

Per le abbreviazioni di nomi ben note tra gli sviluppatori di software, come config e spec, devono essere utilizzate nelle definizioni dell'API anziché la spelling completa. In questo modo, il codice sorgente sarà facile da leggere e scrivere. Nella documentazione formale deve essere utilizzata l'ortografia completa. Esempi:

  • config (configurazione)
  • id (identificatore)
  • spec (specifica)
  • stats (statistiche)
Indietro
Presentazione
Avanti
Struttura delle directory