Projeto voltado para recursos

O objetivo deste Guia de Projeto é ajudar os desenvolvedores a criar APIs em rede simples, consistentes e fáceis de usar. Ao mesmo tempo, 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 arquitetural do REST foi introduzido e projetado principalmente para funcionar bem com o 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 de APIs. Com o protocolo HTTP, os nomes de recursos são mapeados naturalmente para URLs, e os métodos são associados naturalmente aos métodos HTTP POST, GET, PUT, PATCH e DELETE. Isso diminui a quantidade de informações que os desenvolvedores precisam aprender, já que podem se concentrar nos recursos e nos relacionamentos e pressupor que todos os elementos têm um pequeno número de métodos padrão.

Na Internet, as APIs REST HTTP têm tido grande sucesso recentemente. Em 2010, cerca de 74% das APIs de rede pública eram APIs REST HTTP.

Embora as APIs REST HTTP sejam muito famosas na Internet, a quantidade de tráfego transportado por elas é menor do que nas 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 considerariam o uso de APIs REST para enviar esse conteúdo por motivos 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 REST públicas.

Na realidade, as APIs RPC e as APIs REST HTTP são necessárias por vários motivos, e o ideal é que uma plataforma de API tenha o melhor suporte para todos os tipos de APIs. Neste Guia de Projeto, você aprende a projetar e criar APIs em conformidade com este 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 e manipulados por meio de um pequeno conjunto de métodos (também conhecidos como verbos ou operações).

Os métodos padrão das 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, eles geralmente são chamados de recurso e conjunto, 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. Para este 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 associadas 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.

Exemplos

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 de API: gmail.googleapis.com
    • um conjunto de usuários: users/*. Cada usuário tem os seguintes recursos:
      • um conjunto de mensagens: users/*/messages/*
      • um conjunto de conversas: users/*/threads/*
      • um conjunto de marcadores: users/*/labels/*
      • um conjunto de histórico de alterações: users/*/history/*
      • um recurso que representa o perfil do usuário: users/*/profile
      • um recurso que representa as configurações do usuário: users/*/settings

API Cloud Pub/Sub

Ao usar o serviço pubsub.googleapis.com, a API Cloud Pub/Sub é implementada na definição do seguinte modelo de recursos:

  • serviço de API: pubsub.googleapis.com
    • um conjunto de tópicos: projects/*/topics/*.
    • um conjunto de inscrições: projects/*/subscriptions/*.

OBSERVAÇÃO: outras implementações da API Pub/Sub podem escolher diferentes esquemas de nomeação de recursos.

API Cloud Spanner

Ao usar o serviço spanner.googleapis.com, a API Cloud Spanner é implementada na definição do seguinte modelo de recursos:

  • serviço de API: spanner.googleapis.com
    • um conjunto de instâncias: projects/*/instances/*
      • um conjunto de operações de instância: projects/*/instances/*/operations/*
      • um conjunto de bancos de dados: projects/*/instances/*/databases/*
      • um conjunto de operações de banco de dados: projects/*/instances/*/databases/*/operations/*
      • um conjunto de sessões de banco de dados: projects/*/instances/*/databases/*/sessions/*
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…