O Google disponibilizou um Guia de Design de API para criação de APIs HTTP ou RPC. Estes princípios de design são recomendados especialmente para desenvolvedores que criam gRPC APIs conectando-se aos endpoints do Google Cloud.
O Google vem usando internamente esse guia de design desde 2014 ao criar o cloud ou outras APIs de serviços. O guia discute o design de APIs HTTP ou RPC. Embora reconheça os méritos das APIs HTTP (também chamadas APIs REST), mencionando que há momentos em que elas fazem sentido para serem usadas, o Google prefere RPC e especialmente a variante gRPC. Enquanto a maioria das APIs da internet são HTTP, as usadas internamente pelo cloud e provedores de serviços são geralmente RPC, superando amplamente as APIs HTTP, de acordo com o Google.
O Google recomenda uma abordagem baseada no REST para projetar APIs RPC, com o princípio de um ou mais recursos que são operados com métodos. Recursos, também conhecidos como entidades, são identificados através de URIs ou nomes únicos (IDs) seguindo um formato de caminho de rede. Recursos do mesmo tipo podem ser agrupados em coleções.
Os métodos padrão são Create, Delete, Get, List, e Update. É possível criar métodos personalizados para operações que não podem ser mapeadas para um dos padrões, como transações de bancos de dados. Recomenda-se o uso de tantos recursos quanto necessário com um pequeno número de métodos.
As seguintes etapas são sugeridas ao criar recursos:
- Determinar quais tipos de recursos uma API fornece;
- Determinar os relacionamentos entre os recursos;
- Decidir o esquema de nomes dos recursos com base nos tipos e relações;
- Decidir os esquemas dos recursos;
- Adicionar o minímo de métodos para os recursos.
Para o controle de versão, o Google usa versões semânticas representadas por três números como em MAJOR.MINOR.PATCH. Uma versão de pré-lançamento é indicada com um sufixo, como 1.0.0-alfa.
O guia contém mais detalhes e exemplos em recursos, padrões e métodos customizados, padrão de campos, erros, criação de APIs com o proto3 entre outros.