Guia de projeto da API

Publicado em 21/02/2019. Última atualização em 22/07/2020.

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 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 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 documento

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.