O Básico sobre REST APIs
REST, que significa Representational State Transfer, é um padrão de comunicação cliente/servidor apresentado por Roy Fielding em sua dissertação de doutorado pela Universidade da Califórnia em 2000.
Esse padrão é amplamente utilizado em aplicações que disponibilizam APIs (Application Programming Interface), geralmente utilizando o formato JSON e o protocolo HTTP para o tráfego de dados.
Na arquitetura REST, os métodos HTTP, como GET, POST, PUT, PATCH e DELETE, são utilizados para manipular recursos no servidor.
Visão geral dos métodos HTTP utilizados em APIs REST:
GET: Usado para buscar a representação de um recurso, sem modificá-lo. Deve ser idempotente, ou seja, múltiplas solicitações idênticas devem produzir o mesmo resultado até que uma alteração posterior seja feita no recurso. O resultado esperado é o status de resposta 200 (OK) com o conteúdo no corpo da resposta.
POST: Utilizado para criar novos recursos. O resultado esperado é o status de resposta 201 (Created) ou 202 (Accepted) caso a ação tenha sido enfileirada.
PUT: Utilizado para atualizar recursos existentes. Se o recurso não existir, o método pode decidir se cria ou não o recurso. O resultado esperado varia entre os status de resposta 200 (OK), 201 (Created), 204 (No Content) ou 202 (Accepted) caso a ação tenha sido enfileirada.
PATCH: Responsável por atualizações parciais nos recursos, enquanto o PUT é responsável pela atualização completa do recurso. O resultado esperado varia entre os status de resposta 200 (OK), 204 (No Content) ou 202 (Accepted) caso a ação tenha sido enfileirada.
DELETE: Responsável por deletar recursos. O resultado esperado varia entre os status de resposta 200 (OK), 204 (No Content) ou 202 (Accepted) caso a ação tenha sido enfileirada.
Em REST, a abstração principal são os recursos, que podem ser únicos ou coleções. Por exemplo, "clientes" é uma coleção de recursos, enquanto "cliente" é um recurso único. Podemos identificar a coleção de recursos "clientes" pelo caminho "/clientes" e uma entidade única de "cliente" pelo caminho "/clientes/{id-do-cliente}", sendo o "id-do-cliente" um parâmetro do caminho.
Um recurso pode conter uma subcoleção, como a subcoleção "contas" de um "cliente", que pode ser identificada pelo caminho "/clientes/{cliente-id}/contas". Da mesma forma, o recurso único "conta" dentro da subcoleção "contas" pode ser manipulado pelo caminho "/clientes/{cliente-id}/contas/{conta-id}".
Arquétipos de recursos:
Documento:
Um documento se assemelha a uma instância de objeto ou registro de banco de dados, um substantivo, uma coisa. No REST, você pode vê-lo como um único recurso dentro da coleção de recursos, como o caso do cliente dentro da coleção de clientes, mapeado no caminho "/clientes/{cliente-id}".
Utilize o nome do recurso no singular para o arquétipo de documento.
Coleção:
Uma coleção é um diretório de recursos, como no caso em que "clientes" é uma coleção de cliente.
Utilize o nome do recurso no plural para o arquétipo de coleção.
Controlador:
Um recurso de controlador modela um conceito de procedimento. Os recursos do controlador são como funções executáveis, com parâmetros e valores de retorno; entradas e saídas, como no exemplo de validar a conta do cliente mapeado no caminho "/clientes/{cliente-id}/contas/{conta-id}/validar".
Utilize um "verbo" para denotar o arquétipo do controlador.
Boas Práticas para nomeação de recursos:
- Prefira utilizar substantivos para representar recursos.
- Use letras minúsculas nas URLs.
- Use hífens (-) para melhorar a legibilidade dos URLs.
- Não use underscore ou camelCase nas URLs.
- Não use barra final (/) em URLs.
- Não use extensões de arquivo.
- Seja consistente no design da API.
A principal abstração de informações no REST é um recurso. Qualquer informação que possa ser nomeada pode ser um recurso: um documento ou imagem, um serviço temporal (por exemplo, "clima de hoje em Los Angeles"), uma coleção de outros recursos, um objeto não virtual (por exemplo, uma pessoa), e assim por diante. Em outras palavras, qualquer conceito que possa ser alvo de referência de hipertexto de um autor deve se enquadrar na definição de um recurso. Um recurso é um mapeamento conceitual para um conjunto de entidades, não a entidade que corresponde ao mapeamento em um determinado momento.
Roy Fielding
API RESTful
Para que uma API seja considerada RESTful, ela deve atender a certos requisitos. Os requisitos básicos são os seguintes:
- Interface uniforme: A API deve seguir uma interface consistente, com convenções claras para acessar e manipular recursos. Deve-se usar métodos HTTP de forma adequada, como GET, POST, PUT, PATCH e DELETE, para realizar operações nos recursos.
- Cliente-servidor: A arquitetura deve separar a interface do usuário (cliente) da lógica de negócios e armazenamento de dados (servidor). Isso permite que as partes evoluam de forma independente e promove a escalabilidade e a modularidade do sistema.
- Stateless: Cada requisição para o servidor deve conter todas as informações necessárias para ser compreendida e processada, sem depender de um estado mantido pelo servidor. Isso permite que a API seja altamente escalável e simplifica sua implementação.
- Cacheável: A API deve permitir a aplicação de técnicas de cache para melhorar o desempenho. Os recursos devem indicar se podem ser armazenados em cache e, se necessário, devem fornecer mecanismos de controle de cache por meio de cabeçalhos HTTP.
- Sistema em camadas: A arquitetura REST pode ser composta por camadas hierárquicas, onde cada camada tem uma responsabilidade específica. Isso ajuda a separar as preocupações e a promover a escalabilidade, permitindo que diferentes componentes sejam adicionados ou modificados sem afetar as outras camadas.
- Interface HATEOAS (Hypermedia as the Engine of Application State): A API pode fornecer links hipermídia nos dados de resposta, permitindo que os clientes descubram e naveguem pelos recursos relacionados. Essa abordagem promove uma maior descoberta e interação com a API, tornando-a mais autoexplicativa.
Esses requisitos são baseados nos princípios do REST e ajudam a garantir que a API seja interoperável, escalável, flexível e aderente aos conceitos do estilo arquitetural RESTful.
Grande abraço!
Para saber mais: