Design voltado a recursos

O objetivo deste Guia de projeto é ajudar os desenvolvedores a projetar APIs em rede simples, consistentes e fáceis de usar. Ao mesmo tempo, ele também ajuda a convergir projetos de APIs RPC baseadas em soquete com APIs REST baseadas em HTTP.

As APIs RPC geralmente são projetadas em termos de interfaces e métodos. À medida que mais e mais interfaces e métodos são adicionados ao longo do tempo, o resultado pode ser uma superfície de API confusa porque os desenvolvedores precisam aprender cada método individualmente. Esse processo, obviamente, é demorado e propenso a erros.

O estilo arquitetônico de REST foi introduzido, projetado principalmente para funcionar bem com HTTP/1.1, mas também para ajudar a resolver esse problema. O princípio básico dele é a definição de recursos nomeados que possam ser manipulados com um número pequeno de métodos. .Os recursos e métodos são conhecidos como substantivos e verbos das APIs. Com o protocolo HTTP, os nomes de recursos mapeiam naturalmente para URLs, e os métodos mapeiam naturalmente para métodos HTTP POST , GET , PUT , PATCH e DELETE. Isso resulta em muito menos coisas para aprender, pois os desenvolvedores podem se concentrar nos recursos e no relacionamento e presumir que eles têm o mesmo número pequeno de métodos padrão.

Na Internet, as APIs REST HTTP têm tido grande sucesso. Em 2010, cerca de 74% das APIs de rede pública eram APIs HTTP (ou do tipo REST), a maioria usando JSON como formato de transmissão.

Embora as APIs JSON/HTTP sejam muito conhecidas na Internet, a quantidade de tráfego que elas transportam é menor do que as APIs RPC tradicionais. Por exemplo, cerca de metade do tráfego da Internet nos Estados Unidos no horário de pico é conteúdo de vídeo, e poucas pessoas consideram usar APIs JSON/HTTP para disponibilizar esse conteúdo por motivos óbvios de desempenho. Dentro dos data centers, muitas empresas usam APIs RPC baseadas em soquete para transportar a maior parte do tráfego de rede, o que pode envolver dezenas de vezes mais dados (medidos em bytes) do que as APIs JSON/HTTP públicas.

Na realidade, as APIs RPC e as APIs JSON/HTTP são necessárias por vários motivos, e o ideal é que as plataformas de API forneçam o melhor suporte para todos os tipos de APIs. Este Guia de Projeto ajuda você a criar e criar APIs que estejam em conformidade com esse princípio. Para tanto, você aplicará princípios de projeto orientados por recurso para o projeto geral da API e definirá muitos padrões comuns de projeto para melhorar a usabilidade e reduzir a complexidade.

Observação: este guia de projeto explica como aplicar os princípios do REST aos projetos de API independentemente da linguagem de programação, do sistema operacional ou do protocolo de rede. NÃO se trata de um guia unicamente para a criação de APIs REST.

O que é uma API REST?

Uma API REST é modelada em forma de conjuntos de recursos endereçáveis individualmente (os substantivos da API). Os recursos são referenciados pelos respectivos nomes de recurso e manipulados por meio de um pequeno conjunto de métodos (também conhecidos como verbos ou operações).

Métodos padrão para APIs REST do Google (também conhecidos como métodos REST) são List, Get, Create, Update e Delete. Métodos personalizados (também conhecidos como verbos personalizados ou operações personalizadas) também estão disponíveis aos desenvolvedores de APIs para funcionalidades que não mapeiam facilmente para um dos métodos padrão, como transações de banco de dados.

Observação: verbos personalizados não criam verbos HTTP personalizados para compatibilidade com métodos personalizados. Para APIs baseadas em HTTP, eles simplesmente mapeiam os verbos HTTP mais adequados.

Fluxo de projeto

O Guia de Projeto sugere as seguintes etapas ao projetar APIs orientadas por recursos (mais detalhes serão abordados em seções específicas abaixo):

• Determine quais tipos de recursos uma API fornece.
• Determine as relações entre os recursos.
• Decida os esquemas de nomes de recursos com base em tipos e relacionamentos.
• Decida os esquemas de recursos.
• Anexe um conjunto mínimo de métodos aos recursos.

Recursos

Uma API orientada por recursos geralmente é modelada como uma hierarquia de recursos, em que cada node é um recurso simples ou um recurso de conjunto. Por conveniência, são frequentemente chamados de recurso e coleção, respectivamente.

• Um conjunto contém uma lista de recursos do mesmo tipo. Por exemplo, um usuário tem um conjunto de contatos.
• Um recurso tem algum estado e zero ou mais sub-recursos. Cada sub-recurso pode ser um recurso simples ou um recurso de conjunto.

Por exemplo, a API Gmail tem um conjunto de usuários, cada usuário tem um conjunto de mensagens, um conjunto de conversas, um conjunto de marcadores, um recurso de perfil e vários recursos de configuração.

Embora haja um alinhamento conceitual entre sistemas de armazenamento e APIs REST, um serviço com uma API orientada por recursos não é necessariamente um banco de dados, e tem enorme flexibilidade em como ele interpreta recursos e métodos. Por exemplo, criar um evento de calendário (recurso) pode gerar eventos adicionais para convidados, enviar convites de e-mail a convidados, reservar salas de conferência e atualizar agendamentos de videoconferência.

Métodos

A característica principal de uma API orientada por recursos é que ela enfatiza os recursos (modelo de dados) sobre os métodos realizados nos recursos (funcionalidade). Uma típica API orientada por recursos expõe um grande número de recursos com um pequeno número de métodos. Os métodos podem ser os métodos padrão ou métodos personalizados. Neste guia, os métodos padrão são: List, Get, Create, Update e Delete.

Quando a funcionalidade da API mapeia naturalmente para um dos métodos padrão, esse método deve ser usado no projeto dela. Os métodos personalizados podem ser usados em funcionalidades que não são naturalmente mapeadas a um dos métodos padrão. Métodos personalizados oferecem a mesma liberdade de projeto que as APIs RPC tradicionais, que podem ser usadas para implementar padrões de programação comuns, como transações de banco de dados ou análise de dados.

Examples

As seções a seguir apresentam alguns exemplos reais sobre como aplicar o projeto de API orientado por recursos em serviços de grande escala. Você pode encontrar mais exemplos no repositório de APIs do Google.

Nestes exemplos, o asterisco indica um recurso específico fora da lista.

API Gmail

O serviço da API Gmail a implementa e expõe a maior parte das funcionalidades do Gmail. Ele tem o seguinte modelo de recursos:

• Serviço da API: gmail.googleapis.com
  • Uma coleção de usuários: users/*. Cada usuário tem os seguintes recursos:
    • Uma coleção de mensagens: users/*/messages/*.
    • Uma coleção de linhas de execução: users/*/threads/*.
    • Uma coleção de rótulos: users/*/labels/*.
    • Um conjunto de histórico de alterações: users/*/history/*.
    • Um recurso que representa o perfil de usuário: users/*/profile.
    • Um recurso que representa as configurações do usuário: users/*/settings.

API Cloud Pub/Sub

O serviço pubsub.googleapis.com implementa a API Cloud Pub/Sub, que define o seguinte modelo de recursos:

• Serviço da API: pubsub.googleapis.com
  • Um conjunto de tópicos: projects/*/topics/*.
  • Um conjunto de assinaturas: projects/*/subscriptions/*.

Observação :outras implementações da API Pub/Sub podem escolher diferentes esquemas de nomenclatura de recursos.

API Cloud Spanner

O serviço spanner.googleapis.com implementa a API Cloud Spanner, que define o seguinte modelo de recurso:

• Serviço da API: spanner.googleapis.com
  • Uma coleção de instâncias: projects/*/instances/*. Cada instância tem os recursos a seguir.
  • Um conjunto de operações: projects/*/instances/*/operations/*.
  • Um conjunto de bancos de dados: projects/*/instances/*/databases/*. Cada banco de dados tem os recursos a seguir.
    • Um conjunto de operações: projects/*/instances/*/databases/*/operations/*.
    • Um conjunto de sessões: projects/*/instances/*/databases/*/sessions/*.