Convenzioni di denominazione

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

• semplice
• intuitivo
• coerente

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

Poiché molti sviluppatori non sono madrelingua inglese, un obiettivo di questi convenzioni di denominazione è garantire che la maggior parte degli sviluppatori a capire facilmente un'API. A tal fine, incoraggia l'utilizzo 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 l'API che l'API interfaccia di programmazione.
• Se possibile, utilizza una terminologia intuitiva e familiare. Ad esempio, quando descrivi 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 di sovraccaricare i 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. Piuttosto, scegli nomi specifici che a descrivere in modo accurato il concetto di 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, perché ogni nome deve essere valutati nel contesto di altri nomi. Instance, info e service sono esempi di nomi che hanno creato problemi in passato. Nomi deve descrivere in modo chiaro il concetto di API (ad esempio: esempio di cosa?) e distinguerlo da altri concetti pertinenti (ad esempio: "avviso" significa la regola, l'indicatore o notifica?).
• Valuta attentamente l'uso di nomi che potrebbero essere in conflitto con le parole chiave in linguaggi di programmazione più comuni. Questi nomi possono essere utilizzati, ma probabilmente attiveranno un'ulteriore verifica durante la revisione dell'API. Usale con giudizio e con 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 dei servizi 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 pubbliche di Google segui lo schema: xxx.googleapis.com. Ad esempio, il nome del servizio di Google Calendar è calendar.googleapis.com.

Se un'API è composta da più servizi in cui devono essere denominati per favorire la rilevabilità. Un modo per farlo è che i nomi servizio 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 API .proto devono essere coerenti con i Nomi di prodotti e di 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 dell'interfaccia deve utilizzare un nome intuitivo, come Calendar o Macchia. Il nome non deve essere in conflitto con 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ò definire una o più RPC nella sua specifica IDL che corrispondono a quelli su 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. Metodi batch deve utilizzare il sostantivo plurale.

Nota: il caso riportato sopra si riferisce al nome RPC nei buffer di protocollo; i suffissi URI HTTP/JSON utilizzano :lowerCamelCase.

Ciò può essere facilmente confuso quando il verbo pone una domanda su una risorsa secondaria nell'API, che è spesso espresso nello stato 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 prendendo in considerazione aggiungendo CreateBookFromDictation, prendi in considerazione un metodo TranscribeBook .

Nomi dei messaggi

I nomi dei messaggi devono essere brevi e concisi. Evita inutili o ridondanti parole. Spesso gli aggettivi possono essere omessi se non è presente 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 rappresentati meglio con campi facoltativi nel 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 (usa 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 enum

I tipi di enum devono utilizzare nomi in maiuscolo CamelCase.

I valori enum devono utilizzare CAPITALIZED_NAMES_WITH_underSCORES. Ciascuna il valore enum deve terminare con un punto e virgola, non 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 invece essere failure_time_cpu_usage

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

• items_collected dovrebbe invece essere collected_items
• objects_imported dovrebbe invece essere imported_objects

Nomi di campi ripetuti

I campi ripetuti nelle API devono utilizzare forme plurali appropriate. Corrisponde a la convenzione delle API di Google esistenti e l'aspettativa comune 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 includere il forma di verb_time, ad esempio create_time, update_time. Evita di utilizzare al passato per il verbo, 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 per motivi di compatibilità o legacy, tra cui ora normale, durata di 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 stringa deve utilizzare il formato RFC 3339, ad esempio "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 da fuso orario e data, google.type.TimeOfDay deve essere utilizzato 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 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 di risorse deve essere una forma plurale della risorsa che ha un nome. 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;
}

Custodia in 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 abbreviazioni di nomi note tra gli sviluppatori di software, ad esempio config e spec, le abbreviazioni devono essere utilizzate nelle definizioni delle API dell'ortografia completa. In questo modo il codice sorgente sarà più facile da leggere e scrivere. Nella documentazione formale deve essere utilizzata l'ortografia completa. Esempi:

• config (configurazione)
• id (identificatore)
• spec (specifica)
• stats (statistiche)