Convenções de nomenclatura

Para fornecer uma experiência de desenvolvedor consistente em muitas APIs e durante um longo período de tempo, os nomes usados por uma API serão divididos da seguinte maneira:

  • simples
  • intuitivo
  • consistente

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

Como muitos desenvolvedores não são falantes nativos do inglês, um dos objetivos é 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 serão em inglês americano correto. Por exemplo, "license" (em vez de "licence"), "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 "excluir" em vez de "remover".
  • Use o mesmo nome ou termo para o mesmo conceito, inclusive para aqueles compartilhados em APIs.
  • Evite sobrecarga de nomes. 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 mal entendido nos conceitos da API. Em vez disso, escolha nomes específicos que descrevam com precisão o conceito de API. Isso é particularmente importante para nomes que definem elementos de API de primeira ordem, como recursos. Não há lista definitiva de nomes para evitar, porque todo nome será avaliado no contexto de outros nomes. A instância, a informação e o serviço são exemplos de nomes que têm sido problemáticos no passado. Os nomes escolhidos devem descrever claramente o conceito da API (por exemplo: instância de quê?) e distingui-lo de outros conceitos 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 marketing de produtos das APIs, como a API Google Calendar. Eles precisam ser usados de maneira consistente por APIs, IUs, documentação, Termos de Serviço, extratos, contratos comerciais, entre outros. Nas APIs do Google, é necessário usar nomes de produtos aprovados pelas equipes de produtos e marketing.

A tabela abaixo mostra exemplos de todos os nomes de API relacionados e a consistência deles. Segue 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 precisam 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ço das APIs públicas do Google seguem o padrão: xxx.googleapis.com. Por exemplo, o nome do serviço do Google Calendar é calendar.googleapis.com.

Se uma API é composta de vários serviços, eles devem ser nomeados de modo que facilite a detecção do dispositivo. Uma maneira de fazer isso é os nomes dos serviços compartilharem um prefixo comum. Por exemplo, os serviços build.googleapis.com e buildresults.googleapis.com fazem parte da Google Build API.

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 de pacotes para APIs que têm uma versão precisam terminar com a versão. Por exemplo:

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

Uma API abstrata que não está diretamente associada a um serviço, como a Google Watcher API, 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 precisam corresponder aos nomes dos pacotes proto com o prefixo padrão do nome do pacote Java (com., edu., net. e assim por diante). Por exemplo:

package google.calendar.v3;

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

Conjunto de códigos

Nos códigos de conjuntos, é necessário 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ões com nomes de serviços como pubsub.googleapis.com, o termo nome de interface se refere ao nome usado na definição de um service em um arquivo .proto:

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

Você pode pensar no nome do serviço como uma referência à implementação real de um conjunto de APIs, enquanto o nome da 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 de tempo de execução (por exemplo, "File").

No caso raro de um nome de interface entrar em conflito com outro nome na API, é necessário usar um sufixo como Api ou Service para diferenciá-los.

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 dos métodos precisam seguir a convenção de nomenclatura de VerbNoun em palavras concatenadas com maiúsculas, em que o substantivo geralmente é o tipo de recurso.

Verbo Substantivo 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, é recomendável usar o modo imperativo, que é adequado para ordens ou comandos, em vez do modo indicativo, que é próprio para perguntas.

Isso é facilmente confundido quando o verbo está fazendo uma pergunta sobre um sub-recurso na API, que geralmente é expresso no modo indicativo. Por exemplo, pedir que a API crie um livro é claramente CreateBook (no modo imperativo), mas perguntar à API sobre o estado do editor do livro pode usar o modo indicativo, como IsBookPublisherApproved ou NeedsPublisherApproval. Para permanecer no modo imperativo em situações como esta, confie em comandos como "check" (CheckBookPublisherApproved) e "validate" (ValidateBookPublisher).

Os nomes dos métodos não podem incluir preposições (por exemplo, "For", "With", "At", "To"). Geralmente, nomes de métodos com preposições indicam que um novo método está sendo usado, para situações em que seria necessário adicionar um campo a um método existente ou usar outro verbo.

Por exemplo, se uma mensagem CreateBook já existir e você estiver considerando adicionar CreateBookFromDictation, use um método TranscribeBook.

Nomes de mensagens

Os nomes das mensagens precisam 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 é desnecessário quando não há configurações de proxy não compartilhadas.

Nomes de mensagens não podem incluir preposições (por exemplo, "With", "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 dos métodos de RPC precisam ser nomeadas após os nomes do método com o sufixo Request ou Response, respectivamente, a menos que a solicitação do método ou o tipo de resposta seja:

  • 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 precisam usar nomes com LetrasConcatenadasEmMaiúsculas.

Os valores de enum precisam usar NOMES_EM_MAIÚSCULO_COM_SUBLINHADO. Cada valor de enum precisa terminar com um ponto e vírgula, e não uma vírgula. O primeiro valor será denominado 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 do proto2 em que o valor 0 tem um significado diferente de UNSPECIFIED precisam ser nomeadas com o sufixo Value e ter um único campo denominado value.

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

Nomes de campos

As definições de campo nos arquivos .proto usarão nomes_separados_por_sublinhado_em_minúsculo. 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", "at"), por exemplo:

  • reason_for_error deve ser error_reason
  • cpu_usage_at_time_of_failure deve ser failure_time_cpu_usage

Nomes de campos não devem usar adjetivos pós-positivos (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 precisam usar formas plurais adequadas. 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 calendário, google.protobuf.Timestamp precisa ser usado e o nome do campo precisa terminar com time, como start_time ou end_time.

Caso o tempo se refira a uma atividade, o nome do campo precisará ter o formato verb_time, como create_time ou update_time. Evite usar o tempo passado para o verbo, como em created_time ou o 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 precisa 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 precisarã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 dessa string usará o formato RFC 3339, por exemplo, "2014-07-30T10:43:17Z".

Data e hora do dia

Para datas que são independentes do fuso horário e da hora do dia, google.type.Date precisa ser usado e ter o sufixo _date. Se uma data precisa ser representada como uma string, ela precisa estar no formato de data ISO 8601 AAAA-MM-DD, por exemplo, 2014-07-30.

Para horas do dia que são independentes de fuso horário e data, google.type.TimeOfDay precisa ser usado e ter o sufixo _time. Se uma hora do dia precisa ser representada como uma string, ela deve estar no formato 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 precisam incluir a unidade de medida.

xxx_{bytes|width_pixels|meters}

Se a quantidade for uma série de itens, o campo precisa ter o sufixo _count. Por exemplo, node_count.

Campo de filtro de lista

Se uma API aceitar filtragem de recursos retornados pelo método List, o campo que contém a expressão do filtro precisará ser chamado de filter. Por 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, precisa ser uma forma plural do próprio nome do recurso. Por exemplo, um método CalendarApi.ListEvents() precisa ser usado para definir uma mensagem de resposta ListEventsResponse com um campo repetido chamado events referente à 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 campo e valores de enumeração, é necessário que todas as definições nos arquivos .proto usem nomes no formato UpperCamelCase, conforme definido pelo Guia de estilo do Google para Java.

Abreviatura de nomes

Em definições de API, é preciso usar abreviaturas de nomes bem conhecidas entre desenvolvedores de software, como config e spec, em vez da grafia completa. Isso deixará o código-fonte fácil de ser lido e escrito. A ortografia completa deve ser usada nas documentações formais. Exemplos:

  • config (configuração)
  • id (identificador)
  • spec (especificação)
  • stats (estatísticas)
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…