Introdução
Este é um guia de design geral para APIs em rede. Ela é usada no Google desde 2014 e é o guia que o Google segue ao projetar APIs do Cloud e outras APIs do Google. Este guia de design é compartilhado aqui para informar 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 a recursos
- Nomes dos recursos
- métodos padrão
- métodos personalizados
- Campos padrão
- Erros
- Convenções de nomenclatura
- Padrões de projeto
- Documentação
- Como usar o proto3
- Controle de versão
- Compatibilidade
- Estrutura de diretórios
- Estrutura de arquivo
- Glossário