Convenções de nomeação

Para fornecer uma experiência de desenvolvedor consistente em diversas APIs e durante um longo período, os nomes usados por uma API precisam ser:

  • simples
  • intuitivos
  • consistentes

Isso inclui nomes de interfaces, recursos, conjuntos, métodos e mensagens.

Como muitos desenvolvedores não são falantes nativos de inglês, um objetivo dessas convenções de nomenclatura é garantir que a maioria dos desenvolvedores possa entender facilmente uma API. Isso é feito incentivando o uso de um vocabulário simples, consistente e pequeno ao nomear métodos e recursos.

  • Os nomes usados nas APIs devem ser em inglês americano correto. Por exemplo, "license" (em vez de "licence") e "color" (em vez de "colour").
  • Termos curtos geralmente aceitos ou abreviaturas de palavras longas podem ser usados para abreviar. Por exemplo, "API" tem preferência sobre "Interface de programação do aplicativo".
  • Use terminologia intuitiva e familiar sempre que possível. Por exemplo, ao descrever a remoção (e destruição) de um recurso, é preferível usar "delete" em vez de "erase".
  • Use o mesmo nome ou termo para o mesmo conceito, inclusive para aqueles compartilhados em APIs.
  • Evite sobrecarregar um nome. Use nomes diferentes para conceitos diferentes.
  • Evite nomes muito gerais que sejam ambíguos no contexto da API e no ecossistema maior das APIs do Google. Eles podem levar a um entendimento errado dos conceitos da API. Em vez disso, escolha nomes específicos que descrevam com precisão o conceito da API. Isso é especialmente importante para nomes que definem elementos de primeira ordem da API, como recursos. Não há uma lista definitiva de nomes a evitar, pois todos os nomes devem ser avaliados no contexto de outros nomes. "Instance" "info" e "service" são exemplos de nomes que causaram problemas no passado. Os nomes escolhidos devem descrever claramente o conceito da API (por exemplo: instância de quê?) e distingui-lo de outras características relevantes (por exemplo: “alert” significa a regra, o sinal ou a notificação?).
  • Considere cuidadosamente o uso de nomes que possam entrar em conflito com palavras-chave em linguagens de programação comuns. Esses nomes podem ser usados, mas provavelmente desencadearão um exame minucioso durante a revisão da API. Use-os de maneira criteriosa e com moderação.

Nomes de produtos

Os nomes de produtos se referem aos nomes de mercado das APIs, como a API Google Calendar. Os nomes dos produtos precisam ser usados de maneira consistente por APIs, IUs, documentação, Termos de Serviço, extratos, contratos comerciais etc. As APIs do Google precisam usar nomes de produtos aprovados pelas equipes de produto e marketing.

A tabela abaixo mostra exemplos de todos os nomes de API relacionados e a consistência deles. Seguem abaixo, nesta página, mais detalhes sobre os respectivos nomes e as convenções.

Nome da API Exemplo
Nome do produto Google Calendar API
Nome do serviço calendar.googleapis.com
Nome do pacote google.calendar.v3
Nome da interface google.calendar.v3.CalendarService
Diretório de origem //google/calendar/v3
Nome da API calendar

Nomes de serviços

Os nomes de serviços devem ser nomes de DNS sintaticamente válidos (em conformidade com o RFC 1035) que possam ser resolvidos para um ou mais endereços de rede. Os nomes de serviços das APIs públicas do Google seguem este padrão: xxx.googleapis.com. Por exemplo, o nome de serviço do Google Agenda é calendar.googleapis.com.

Se uma API é composta de vários serviços, eles devem ser nomeados de modo a serem facilmente detectáveis. Uma maneira de fazer isso é garantir que os nomes de serviços compartilhem um prefixo comum. Por exemplo, os serviços build.googleapis.com e buildresults.googleapis.com fazem parte da API Google Build.

Nomes de pacotes

Os nomes de pacotes declarados nos arquivos .proto da API devem ser consistentes com os nomes de produtos e serviços. Os nomes dos pacotes devem usar os nomes de componentes no singular para evitar misturar nomes no singular e no plural. Os nomes dos pacotes não podem usar sublinhados. Os nomes de pacotes para APIs com controle de versões precisam terminar com a versão. Exemplo:

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

Uma API abstrata que não está diretamente associada a um serviço, como a API Google Watcher, deve usar nomes de pacotes proto consistentes com o nome do produto:

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

Os nomes de pacotes Java especificados nos arquivos .proto da API devem corresponder aos nomes de pacotes proto com o prefixo padrão do nome do pacote Java (com., edu., net. etc.). Exemplo:

package google.calendar.v3;

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

IDs de coleções

Os IDs de coleções precisam usar a forma plural e lowerCamelCase, além da ortografia e semântica do inglês americano. Por exemplo, events, children ou deletedEvents.

Nomes de interfaces

Para evitar confusão com os nomes de serviços, como pubsub.googleapis.com, o termo nome de interface refere-se ao nome usado ao definir um service em um arquivo .proto:

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

Você pode pensar no nome de serviço como uma referência à implementação real de um conjunto de APIs, enquanto o nome de interface refere-se à definição abstrata de uma API.

Um nome de interface deve usar um substantivo intuitivo, como Calendar ou Blob. O nome não deve entrar em conflito com conceitos bem estabelecidos nas linguagens de programação e nas bibliotecas do ambiente de execução (por exemplo, "File").

No caso raro em que o nome de interface entra em conflito com outro nome na API, um sufixo (por exemplo, Api ou Service) deve ser usado para eliminar a ambiguidade.

Nomes de métodos

Um serviço pode, em sua especificação de IDL, definir um ou mais métodos de RPC que correspondem a métodos de conjuntos e recursos. Os nomes de métodos devem seguir a convenção de nomenclatura de VerbNoun com palavras concatenadas que têm maiúsculas no início de cada termo, em que o substantivo é normalmente o tipo de recurso.

Verbo Noun Nome do método Mensagem de solicitação Mensagem de resposta
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

Na parte do verbo no nome do método, é necessário usar o modo imperativo, que é adequado para ordens ou comandos, em vez do modo indicativo, que é próprio para perguntas.

Nos métodos padrão, a parte do substantivo do nome do método precisa estar no singular exceto List, e precisa ser no plural para List. Nos métodos personalizados, o substantivo pode estar no singular ou no plural, conforme apropriado. Os métodos em lote precisam usar o substantivo no plural.

Isso é facilmente confundido quando o verbo está fazendo uma pergunta sobre um sub-recurso na API, que geralmente é expresso no modo indicativo. Por exemplo, para solicitar à API a criação de um livro, use o método CreateBook (no modo imperativo). Mas, para solicitar à API informações sobre o estado da editora do livro, use o modo indicativo, como IsBookPublisherApproved ou NeedsPublisherApproval. Para permanecer no modo imperativo em situações como essa, use comandos como "check" (CheckBookPublisherApproved) e "validate" (ValidateBookPublisher).

Os nomes de métodos não podem incluir preposições (por exemplo, "for", "with", "at" e "to"). Geralmente, nomes de métodos com preposições indicam que um método novo está sendo usado, quando seria necessário adicionar um campo a um método atual ou usar outro verbo.

Por exemplo, se uma mensagem CreateBook já existir e você estiver pensando em adicionar CreateBookFromDictation, considere usar um método TranscribeBook.

Nomes de mensagens

Os nomes de mensagens devem ser curtos e concisos. Evite palavras desnecessárias ou redundantes. Geralmente, os adjetivos podem ser omitidos se não houver uma mensagem correspondente sem o adjetivo. Por exemplo, o Shared em SharedProxySettings será desnecessário se não houver configurações de proxy não compartilhadas.

Nomes de mensagens não podem incluir preposições (por exemplo, "with" e "for"). Geralmente, nomes de mensagens com preposições são melhor representados usando campos opcionais na mensagem.

Mensagens de solicitação e resposta

As mensagens de solicitação e resposta para métodos de RPC devem ser nomeadas com o nome do método seguido pelos sufixos Request e Response, respectivamente, a menos que esses itens sejam:

  • uma mensagem vazia (use google.protobuf.Empty);
  • um tipo de recurso; ou
  • um recurso que representa uma operação.

Isso geralmente se aplica a solicitações ou respostas usadas nos métodos padrão Get, Create, Update ou Delete.

Nomes de enum

Os tipos de enum devem usar nomes no formato UpperCamelCase.

Os valores enum devem usar NOMES_EM_MAIÚSCULA_COM_SUBLINHADOS. Cada valor de enum deve terminar com um ponto e vírgula, não uma vírgula. O primeiro valor deve ser nomeado TIPO_DE_ENUM_NÃO_ESPECIFICADO, já que ele é retornado quando um valor de enum não está explicitamente especificado.

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

Wrappers

As mensagens que encapsulam os tipos de enum proto2 em que o valor 0 tem um significado diferente de UNSPECIFIED devem ser nomeadas com o sufixo Value e ter um único campo chamado value.

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

Nomes de campo

As definições de campo nos arquivos .proto devem usar nomes_separados_por_sublinhado_em_minúscula. Esses nomes serão mapeados para a convenção de nomenclatura nativa no código gerado para cada linguagem de programação.

Os nomes de campo não podem incluir preposições (por exemplo, "for", "during" e "at"), por exemplo:

  • reason_for_error deve ser error_reason
  • cpu_usage_at_time_of_failure deve ser failure_time_cpu_usage

Nomes de campo não devem usar adjetivos pospostos (modificadores colocados após o substantivo), por exemplo:

  • items_collected deve ser collected_items
  • objects_imported deve ser imported_objects

Nomes de campo repetidos

Os campos repetidos nas APIs devem usar formas plurais corretas. Isso corresponde à convenção das APIs do Google existentes e à expectativa comum dos desenvolvedores externos.

Tempo e duração

Para representar um ponto no tempo independentemente de qualquer fuso horário ou agenda, google.protobuf.Timestamp deve ser usado. E o nome do campo deve terminar com time, como start_time e end_time.

Se o tempo se referir a uma atividade, o nome do campo deverá ter a forma de verb_time, como create_time e update_time. Evite usar o tempo passado do verbo, como created_time ou last_updated_time.

Para representar um período entre dois pontos no tempo, independentemente de qualquer calendário e conceitos, como "dia" ou "mês", google.protobuf.Duration deve ser usado.

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

Caso você tenha que representar campos relacionados a tempo usando um tipo de número inteiro para fins de compatibilidade ou legado, como horário, duração, atraso e latência, os nomes dos campos deverão ter o seguinte formato:

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

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

Se for preciso representar o carimbo de data/hora usando o tipo de string por motivos legados ou de compatibilidade, os nomes dos campos não devem incluir nenhum sufixo de unidade. A representação da string deve usar o formato RFC 3339, por exemplo, "2014-07-30T10:43:17Z".

Data e hora do dia

Para datas independentes do fuso horário e da hora do dia, google.type.Date deve ser usado e ter o sufixo _date. Se for necessário representar uma data como uma string, o formato deverá ser de acordo com a norma ISO 8601 AAAA-MM-DD, por exemplo, 2014-07-30.

Para horários do dia independentes do fuso horário e da data, google.type.TimeOfDay deve ser usado e ter o sufixo _time. Se for necessário representar uma hora do dia como uma string, o formato deverá ser de acordo com a norma ISO 8601 de 24 horas (HH:MM:SS [.FFF]), por exemplo, 14:55:01.672.

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

Quantidades

As quantidades representadas por um tipo de número inteiro devem incluir a unidade de medida.

xxx_{bytes|width_pixels|meters}

Se a quantidade for um número de itens, o campo deverá ter o sufixo _count, por exemplo, node_count.

Campo de filtro de lista

Se uma API for compatível com a filtragem de recursos retornados pelo método List, o campo que contém a expressão de filtro deverá ser nomeado de filter. Exemplo:

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

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

Resposta de lista

O nome do campo na mensagem de resposta do método List, que contém a lista de recursos, deve estar na forma plural do nome do recurso. Por exemplo, um método CalendarApi.ListEvents() deve definir uma mensagem de resposta ListEventsResponse com um campo repetido chamado events para a lista de recursos retornados.

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

Letras concatenadas

Exceto para nomes de campos e valores enum, todas as definições dentro de arquivos .proto devem usar nomes no formato UpperCamelCase, conforme definido pelo Guia de estilo do Google para Java (em inglês).

Abreviatura de nomes

Abreviaturas de nomes conhecidos entre desenvolvedores de software, como config e spec, devem ser usadas nas definições da API em vez da ortografia completa. Isso facilitará a leitura e a escrita do código-fonte. A ortografia completa deve ser usada em documentações formais. Exemplos:

  • config (configuração)
  • id (identificador)
  • spec (especificação)
  • stats (estatísticas)
Anterior
Erros
Próxima
Padrões de projeto