Convenzioni di denominazione

Per offrire agli sviluppatori un'esperienza coerente su molte API e per 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, uno degli obiettivi di queste convenzioni di denominazione è garantire che la maggior parte degli sviluppatori possa capire facilmente un'API. Lo fa incoraggiando l'uso di un vocabolario semplice, coerente e ridotto quando si nominano metodi e risorse.

• I nomi utilizzati nelle API devono essere nell'inglese americano corretto. Ad esempio, licenza (anziché licenza), colore (anziché colore).
• Le forme brevi o le abbreviazioni comunemente accettate di parole lunghe possono essere utilizzate per brevità. Ad esempio, l'API è preferibile rispetto all'interfaccia di programmazione di un'applicazione.
• Se possibile, utilizza una terminologia intuitiva e familiare. Ad esempio, quando si descrive la rimozione (e l'eliminazione) di una risorsa, l'eliminazione è preferita rispetto all'eliminazione.
• Utilizza lo stesso nome o termine per lo stesso concetto, anche per i concetti condivisi tra le API.
• Evita di sovraccaricare i nomi. Utilizza nomi diversi per concetti diversi.
• Evita nomi eccessivamente generici che sono ambigui nel contesto dell'API e del più ampio ecosistema delle API di Google. Possono portare a fraintendimenti dei concetti delle API. Scegli invece nomi specifici che descrivano accuratamente il concetto dell'API. Ciò è particolarmente importante per i nomi che definiscono elementi API di primo ordine, ad esempio le risorse. Non esiste un elenco definitivo di nomi da evitare, poiché ogni nome deve essere valutato nel contesto di altri nomi. Istanza, informazioni e servizio sono esempi di nomi che sono stati problematici in passato. I nomi scelti 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 essere in conflitto con parole chiave nei linguaggi di programmazione comuni. Questi nomi possono essere utilizzati, ma probabilmente avvieranno ulteriori accertamenti durante la revisione dell'API. Usali con prudenza e parsimonia.

Nomi dei prodotti

I nomi di prodotto si riferiscono ai nomi di marketing di API, come API Google Calendar. I nomi dei prodotti devono essere utilizzati in modo coerente da API, UI, documentazione, Termini di servizio, estratti conto, contratti commerciali e così via. Le API di Google devono utilizzare nomi di prodotto approvati dai team di prodotto e di marketing.

La tabella seguente mostra esempi di tutti i nomi delle API correlati e della loro coerenza. Vai più avanti in questa pagina per maggiori dettagli sui rispettivi nomi e sulle loro convenzioni.

Nome API	Esempio
Nome prodotto	Google Calendar API
Nome servizio	calendar.googleapis.com
Nome pacchetto	google.calendar.v3
Nome dell'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 (secondo RFC 1035) che possono essere risolti in uno o più indirizzi di rete. I nomi dei servizi delle API pubbliche di Google 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, dovrebbero essere denominati in modo da facilitare 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 sono entrambi servizi che fanno 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 i nomi di servizio. I nomi dei pacchetti devono usare nomi di componenti singolari per evitare nomi misti di componenti singolari e plurali. I nomi dei pacchetti non devono contenere trattini bassi. I nomi dei pacchetti per le API con controllo delle versioni devono terminare con la versione. Ad esempio:

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

Un'API astratta non direttamente associata 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é l'ortografia e la semantica dell'inglese americano. Ad esempio: events, children o deletedEvents.

Nomi delle interfacce

Per evitare confusione con i nomi di servizio, ad esempio pubsub.googleapis.com, il termine nome interfaccia si riferisce al nome utilizzato quando definisci service in un file .proto:

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

Il nome del servizio può essere paragonato all'implementazione effettiva di un set 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 Blob. Il nome non deve essere in conflitto con concetti consolidati nei linguaggi di programmazione e nelle relative librerie di runtime (ad esempio, File).

Nel raro caso in cui un nome dell'interfaccia entri in conflitto con un altro nome all'interno dell'API, dovrebbe utilizzare un suffisso (ad esempio Api o Service) per distinguerlo.

Nomi dei metodi

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

Verbo	Noun	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 verbale del nome del metodo deve utilizzare l'umore imperativo, che è per ordini o comandi, piuttosto che lo stato indicativo per le domande.

Per i metodi standard, la parte del nome del metodo deve essere singolare per tutti i metodi tranne List e deve essere 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.

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

Questo può essere facilmente confuso quando il verbo pone una domanda su una sottorisorsa nell'API, che è spesso espressa nello stato d'animo indicativo. Ad esempio, ordinare l'API per la creazione di un libro è chiaramente CreateBook (in stato d'animo imperativo), ma chiedere all'API informazioni sullo stato dell'editore del libro potrebbe utilizzare lo stato indicativo, come IsBookPublisherApproved o NeedsPublisherApproval. Per rimanere nello stato d'animo imperativo in situazioni come questa, utilizza comandi come "check" (CheckBookPublisherApproved) e "convalida" (ValidateBookPublisher).

I nomi dei metodi non devono includere preposizioni (ad es. "For", "With", "At", "To"). In genere, i nomi dei metodi con preposizioni indicano che viene utilizzato un nuovo metodo quando invece un campo deve essere aggiunto a un metodo esistente oppure il metodo deve utilizzare un verbo diverso.

Ad esempio, se esiste già un messaggio CreateBook e stai prendendo in considerazione l'aggiunta di CreateBookFromDictation, prendi in considerazione il metodo TranscribeBook.

Nomi dei messaggi

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

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.

Messaggi di richiesta e risposta

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

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

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

Nomi enum

I tipi di enum devono utilizzare i nomi UpperCamelCase.

I valori enum devono utilizzare CAPITALIZED_NAMES_WITH_UNDERSCORES. Ogni valore enum deve terminare con un punto e virgola, non una virgola. Il primo valore deve essere denominato ENUM_TYPE_UNSPECIFIED poiché viene restituito quando non viene specificato esplicitamente un valore enum.

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 enum proto2 in cui il valore 0 ha un significato diverso da UNSPECIFIED devono essere chiamati 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 lower_case_underscore_separate_names. Questi nomi saranno mappati alla convenzione di denominazione nativa nel codice generato per ciascun linguaggio di programmazione.

I nomi dei campi non devono includere preposizioni (ad es. "for", "during", "at"), ad esempio:

• reason_for_error dovrebbe invece 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 (modificatori posizionati dopo il sostantivo), 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 le forme plurali corrette. Ciò corrisponde alla convenzione delle API di Google esistenti e alle aspettative comuni degli sviluppatori esterni.

Tempo e durata

Per rappresentare un momento specifico indipendente da qualsiasi fuso orario o calendario, è necessario utilizzare google.protobuf.Timestamp 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 il formato verb_time, ad esempio create_time, update_time. Evita di usare il passato per il verbo, ad esempio created_time o last_updated_time.

Per rappresentare un intervallo di tempo tra due punti temporali indipendenti da qualsiasi calendario e concetti come "giorno" o "mese", è necessario utilizzare google.protobuf.Duration.

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 legacy o di compatibilità, tra cui l'ora effettiva, la durata, il ritardo e la 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 legacy o di compatibilità, i nomi dei campi non devono includere alcun suffisso di unità. La rappresentazione della 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, deve essere utilizzato google.type.Date, che deve avere il suffisso _date. Se una data deve essere rappresentata come una stringa, deve essere nel formato di data ISO 8601 AAAA-MM-GG, ad es. 2014-07-30.

Per le ore del giorno indipendenti dal fuso orario e dalla data, google.type.TimeOfDay deve essere utilizzato, che deve avere il suffisso _time. Se un'ora del giorno deve essere rappresentata come una stringa, deve essere nel formato dell'ora 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;
}

Elenco di risposte

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 stesso. Ad esempio, un metodo CalendarApi.ListEvents() deve definire un messaggio di risposta ListEventsResponse con un campo ripetuto denominato 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 a cammello

Ad eccezione dei nomi dei campi e dei valori di enumerazione, tutte le definizioni all'interno dei file .proto devono utilizzare nomi UpperCamelCase, come definito dallo stile Java di Google.

Abbreviazione del nome

Per le abbreviazioni di nomi note tra gli sviluppatori di software, come config e spec, nelle definizioni dell'API devono essere utilizzate le abbreviazioni dovrebbero essere utilizzate invece dell'ortografia completa. In questo modo il codice sorgente sarà facile da leggere e scrivere. Nelle documentazioni formali, dovrebbe essere utilizzata l'ortografia completa. Esempi:

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