Introdução
Este é um guia geral de criação de APIs em rede que é usado no Google desde 2014 para desenvolver as APIs do Cloud e outras APIs do Google. Compartilhamos este guia para instruir os desenvolvedores externos e facilitar o trabalho em conjunto.
Os des envolvedores do Cloud Endpointsm podem achar este guia particularmente útil ao projetar APIs de gRPC, e é altamente recomendável que esses desenvolvedores usem esses princípios de design. No entanto, não obrigamos o uso. Você pode usar o Cloud Endpoints e o gRPC sem seguir o guia.
Este guia aplica-se tanto às APIs REST quanto às APIs RPC, com foco específico nas APIs gRPC. As APIs gRPC usam buffers de protocolo para definir a superfície da API e aplicam a configuração de serviço da API para configurar os serviços, incluindo mapeamento HTTP, geração de registros e monitoramento. Os recursos de mapeamento HTTP são usados pelas APIs do Google e pelas APIs gRPC do Cloud Endpoints para JSON/HTTP para a transcodificação de RPC/buffers de protocolo.
Este guia é um documento em construção, e mais adições serão feitas ao longo do tempo conforme novos estilos e padrões de projeto forem adotados e aprovados. Considerando isso, ele nunca será completo e sempre haverá um amplo espaço para a arte e a construção de projetos da API.
Convenções usadas neste guia
As palavras-chave de nível de exigência "PRECISA", "NÃO PODE", "OBRIGATÓRIO", "DEVERÁ", "NÃO DEVERÁ", "DEVE", "NÃO DEVE", "RECOMENDADO", "PODE" e "OPCIONAL" usadas neste documento serão interpretadas conforme descrito na RFC 2119.
Neste documento, essas palavras-chave são destacadas usando a fonte em negrito.
Seções
Design voltado para recursos
Para informações sobre como implementar o design orientado a recursos para APIs RPC e REST, consulte AIP-121.
Nomes dos recursos
Para informações sobre nomes de recursos, consulte AIP-122.
métodos padrão
Para informações gerais sobre métodos, consulte AIP-130.
Para informações sobre métodos padrão, consulte as seguintes AIPs:
- Para
Get, consulte AIP-131. - Para
List, consulte AIP-132. - Para
Create, consulte AIP-133. - Para
Update, consulte AIP-134. - Para
Delete, consulte AIP-135.
métodos personalizados
Para informações sobre métodos personalizados, consulte AIP-136.
Temas adicionais
Para informações sobre os seguintes tópicos, consulte as AIPs relacionadas.
- Para campos padrão, consulte AIP-148.
- Para erros, consulte AIP-193.
- Para padrões de design, consulte as orientações do AIP sobre padrões de design.
- Para a documentação da API inline, consulte AIP-192.
- Para saber como usar o proto3, consulte a seção "Sintaxe" do AIP-191.
- Para saber mais sobre controle de versão, consulte AIP-185.
- Para saber mais sobre compatibilidade com versões anteriores, consulte AIP-180.
- Para saber mais sobre a estrutura de arquivos, consulte a seção "Layout de arquivo" do AIP-191.
- Para consultar o Glossário de termos, consulte AIP-9.
Para informações sobre os seguintes tópicos, consulte as páginas relacionadas neste guia.