Guia de design de APIs

Publicado em 21/02/2019. Registro de mudanças

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 se aplica a APIs REST e RPC, com foco específico nas APIs gRPC. As APIs do gRPC usam buffers de protocolo para definir a superfície da API e a configuração do serviço de 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 Google e pelo gRPC do Cloud Endpoints para JSON/HTTP em 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