Introdução
Este é um guia de design geral para APIs em rede. É usada na Google desde 2014 e é o guia que a Google segue quando cria APIs Cloud e outras APIs Google. Este guia de design é partilhado aqui para informar os programadores externos e facilitar o nosso trabalho em conjunto.
Os programadores do Cloud Endpoints podem considerar este guia particularmente útil ao criar APIs gRPC, e recomendamos vivamente que estes programadores usem estes princípios de design. No entanto, não exigimos a sua utilização. Pode usar os Cloud Endpoints e o gRPC sem seguir o guia.
Este guia aplica-se às APIs REST e às APIs RPC, com foco específico nas APIs gRPC. As APIs gRPC usam buffers de protocolo para definir a respetiva superfície da API e a configuração dos serviços de API para configurar os respetivos serviços de API, incluindo o mapeamento HTTP, o registo e a monitorização. As funcionalidades de mapeamento HTTP são usadas pelas APIs Google e pelas APIs gRPC do Cloud Endpoints para transcodificação de JSON/HTTP para Protocol Buffers/RPC.
Este guia é um documento dinâmico e serão feitas adições ao mesmo ao longo do tempo à medida que forem adotados e aprovados novos padrões de estilo e design. Nesse sentido, nunca vai estar completa e haverá sempre espaço suficiente para a arte e a técnica do design de APIs.
Convenções usadas neste guia
As palavras-chave de nível de requisito "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" e "OPTIONAL" usadas neste documento devem ser interpretadas conforme descrito na RFC 2119.
Neste documento, essas palavras-chave são realçadas com o tipo de letra negrito.
Secções
Design orientado para recursos
Para ver informações sobre a implementação do design orientado para recursos para APIs REST e RPC, consulte o AIP-121.
Nomes de recursos
Para obter informações sobre os nomes dos recursos, consulte o AIP-122.
Métodos padrão
Para informações gerais sobre métodos, consulte o artigo AIP-130.
Para obter 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 o
Delete, consulte o AIP-135
Métodos personalizados
Para obter informações sobre métodos personalizados, consulte o AIP-136.
Tópicos adicionais
Para informações sobre os seguintes tópicos, consulte as respetivas APIs relacionadas.
- Para campos padrão, consulte AIP-148
- Para Erros, consulte AIP-193
- Para padrões de design, consulte as diretrizes da AIP sobre padrões de design
- Para documentação da API inline, consulte AIP-192
- Para usar o proto3, consulte a secção Sintaxe do AIP-191
- Para controlo de versões, consulte AIP-185
- Para retrocompatibilidade, consulte o AIP-180
- Para Estrutura de ficheiros, consulte a secção Esquema de ficheiros do AIP-191
- Para ver um glossário de termos, consulte o AIP-9
- Para convenções de nomenclatura, consulte o AIP-190
Para obter informações sobre os seguintes tópicos, consulte as respetivas páginas relacionadas neste guia.