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.
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 essereerror_reason
cpu_usage_at_time_of_failure
dovrebbe invece esserefailure_time_cpu_usage
I nomi dei campi non devono utilizzare aggettivi postpositivi (modificatori posizionati dopo il sostantivo), ad esempio:
items_collected
dovrebbe invece esserecollected_items
objects_imported
dovrebbe invece essereimported_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)