Skip to main content

Rest | Restful | HATEOAS

  • Rest | Restful | HATEOAS

Rest e RestFul​

API REST e RESTful: Entendendo os Conceitos

Uma API (Interface de Programação de Aplicações) é um conjunto de regras e definições que permite que diferentes softwares se comuniquem de forma eficiente. As APIs são fundamentais para desenvolver aplicações que interagem com outros sistemas ou componentes sem necessidade de conhecer detalhes da implementação interna.

REST (Representational State Transfer) é um estilo arquitetural para sistemas distribuídos, como a Web. Ele define um conjunto de restrições que, quando seguidas, facilitam a criação de serviços web escaláveis e flexíveis. Uma API que adota o estilo arquitetural REST é frequentemente chamada de API REST.

Características Principais de uma API REST:

  1. Comunicação Sem Estado (Stateless): Cada requisição do cliente para o servidor deve conter todas as informações necessárias para entender e responder à requisição. O servidor não deve armazenar nenhum estado sobre o cliente entre as requisições.

  2. Interface Uniforme (Uniform Interface): A interface entre cliente e servidor deve ser uniforme e padronizada. Isso inclui o uso de URIs para identificar recursos e o uso de métodos HTTP (GET, POST, PUT, DELETE, etc.) de forma padrão para interagir com esses recursos.

  3. Sistema de Camadas (Layered System): O cliente não precisa saber se está comunicando diretamente com o servidor real ou intermediários. Isso permite a construção de sistemas escaláveis e simplifica componentes intermediários, como proxies e gateways.

  4. Cacheável (Cacheable): As respostas devem ser definidas como cacheáveis ou não cacheáveis para evitar que clientes reutilizem dados desatualizados, o que melhora a eficiência e a escalabilidade.

  5. Recursos (Resources): Em REST, os dados ou serviços são tratados como recursos e podem ser identificados usando URIs. Cada recurso é representado por um ou mais formatos de dados (como JSON, XML).

  6. Código sob Demanda (Optional): Servidores REST podem, opcionalmente, estender ou personalizar a funcionalidade de um cliente, enviando código executável (JavaScript, por exemplo).

RESTful refere-se a APIs ou serviços web que seguem fielmente os princípios e restrições do estilo arquitetural REST. Uma API RESTful é projetada para ser simples de entender e fácil de usar, fazendo uso completo das operações HTTP padrão.

Diferenças entre API REST e RESTful:

  • API REST: Pode ser qualquer API que se comunica usando protocolos HTTP, mas não segue todas as restrições do estilo arquitetural REST de forma rigorosa.
  • API RESTful: É uma API que estritamente adere às restrições REST, oferecendo uma interação mais previsível e padronizada.

Exemplo de Operações RESTful:

  • GET /api/users: Lista todos os usuários.
  • GET /api/users/123: Retorna detalhes do usuário com ID 123.
  • POST /api/users: Cria um novo usuário com os dados fornecidos no corpo da requisição.
  • PUT /api/users/123: Atualiza o usuário com ID 123 com os novos dados fornecidos.
  • DELETE /api/users/123: Remove o usuário com ID 123.

Vantagens de Usar APIs RESTful:

  • Simplicidade e Facilidade de Uso: Uma API RESTful é fácil de entender e usar.
  • Flexibilidade: Pode ser usado para construir APIs que podem ser consumidas por diferentes tipos de clientes, incluindo navegadores e dispositivos móveis.
  • Escalabilidade: Devido à natureza sem estado e ao sistema de camadas, é mais fácil escalar aplicações RESTful.
  • Interoperabilidade: Facilita a integração com diferentes sistemas e tecnologias.

Conclusão:

As APIs REST e RESTful são fundamentais no desenvolvimento de aplicações modernas, permitindo que diferentes sistemas comuniquem-se de maneira eficiente e escalável. A aderência aos princípios RESTful garante uma interface consistente e padronizada, facilitando o desenvolvimento e a manutenção de aplicações distribuídas.

HATEOAS​

HATEOAS: Entendendo Hypermedia as the Engine of Application State

O termo HATEOAS (Hypermedia as the Engine of Application State) é um componente crucial dentro do conjunto de princípios definidos por REST (Representational State Transfer), proposto por Roy Fielding em sua dissertação de doutorado. HATEOAS é uma das restrições que eleva uma API para ser considerada verdadeiramente RESTful.

O Que É HATEOAS?​

HATEOAS é um princípio que guia a interação com serviços web RESTful, enfatizando que a navegação entre pontos da API deve ser dinâmica, guiada por hiperlinks disponíveis nas respostas fornecidas pelos servidores. Ou seja, um cliente interage com uma aplicação web RESTful exclusivamente através de hiperlinks que são fornecidos dinamicamente nas respostas. Esses hiperlinks informam ao cliente quais outras ações são possíveis a partir do estado atual do aplicativo.

Características Principais de HATEOAS​

  1. Navegação Dinâmica: Em vez de o cliente codificar URLs estáticas (endereços) para acessar recursos, ele segue links fornecidos pelo servidor. Isso significa que o cliente não precisa saber sobre como construir URLs para interagir com o serviço, mas apenas entender e navegar pelos links fornecidos.

  2. Descoberta de Ações: Através dos hiperlinks, o cliente pode descobrir quais operações são possíveis em tempo real. Por exemplo, se um recurso não pode mais ser deletado, a resposta não incluirá um link para a ação de deleção.

  3. Desacoplamento: Como os clientes dependem das respostas do servidor para executar ações, há menos acoplamento entre o cliente e o servidor. O servidor pode mudar suas URLs sem quebrar os clientes, desde que mantenha os mesmos relações e atributos de link nas respostas.

  4. Representação de Estado: Hipermedia (hipertexto, imagens, formulários, links, etc.) é usada para representar o estado atual do recurso, e as possíveis transições de estado são fornecidas como links.

Exemplo de HATEOAS​

Considere um exemplo de uma API RESTful que gerencia informações de usuários. Uma resposta que segue o princípio HATEOAS para uma solicitação GET para um usuário específico pode parecer com:

{
  "id": 123,
  "name": "Alice",
  "email": "alice@example.com",
  "links": [
    {
      "rel": "self",
      "href": "http://api.example.com/users/123"
    },
    {
      "rel": "edit",
      "href": "http://api.example.com/users/123/edit"
    },
    {
      "rel": "avatar",
      "href": "http://api.example.com/users/123/avatar"
    },
    {
      "rel": "friends",
      "href": "http://api.example.com/users/123/friends"
    }
  ]
}

Análise do Exemplo:

  • "rel" representa o tipo de relação que esse link tem com o recurso atual.
  • "href" contém o URI que você pode seguir para realizar a ação ou acessar o recurso relacionado.
  • "self" indica um link para o próprio recurso.
  • "edit" fornece um link para editar o usuário.
  • "avatar" é um link para acessar ou modificar o avatar do usuário.
  • "friends" mostra onde acessar ou modificar a lista de amigos do usuário.

Vantagens do Uso de HATEOAS​

  1. Exploração e Navegação Automática: Clientes podem explorar a API de forma mais autônoma, sem requerer documentação externa detalhada para cada possível ação.

  2. Adaptabilidade: Permite que a API evolua com menos impacto nos clientes, pois as mudanças em URIs são transparentes para os clientes que seguem links em vez de construí-los.

  3. Auto-Documentação: As respostas contêm informações suficientes para o cliente entender o que pode fazer a seguir, o que pode reduzir a necessidade de documentação externa detalhada.

  4. Resiliência: A aplicação cliente se torna mais resistente a mudanças no servidor, pois segue a lógica fornecida dinamicamente pelas respostas.

Conclusão​

O princípio de HATEOAS é um passo além na criação de APIs verdadeiramente RESTful, proporcionando uma maior flexibilidade e desacoplamento entre cliente e servidor. Seguir este princípio pode aumentar a robustez e longevidade da API, permitindo que clientes e servidores evoluam de maneira mais independente e coordenada.

Richardson Maturity Model​

Video explicativo

A Richardson Maturity Model (ou Modelo de Maturidade de Richardson) é uma abordagem que avalia a maturidade de uma API REST, especialmente em termos de como ela segue os princípios RESTful definidos por Roy Fielding. Criado por Leonard Richardson, esse modelo categoriza APIs em quatro níveis de maturidade, numerados de 0 a 3, onde cada nível representa uma maior conformidade com os princípios REST. Esse modelo ajuda a identificar quanto a API está de fato aproveitando as características e potencialidades da arquitetura RESTful.

Aqui estão os níveis do modelo e o que eles representam:

Nível 0 - The Swamp of POX​

No primeiro nível, também chamado de “o pântano do POX” (Plain Old XML), a API é basicamente um único endpoint que responde a todas as requisições de uma forma genérica. Ou seja, ela tende a usar um único método, como POST, para todas as operações (create, read, update e delete). Esse nível não explora as capacidades da arquitetura RESTful.

Exemplo: Enviar uma requisição POST para /api/operacao com diferentes parâmetros para definir a ação, sem seguir um padrão de operações HTTP (GET, POST, PUT, DELETE).

Nível 1 - Recursos Individuais​

No segundo nível, a API começa a identificar recursos específicos, e cada recurso tem um endpoint próprio. Ainda que isso já seja um avanço, é comum que a API não siga as boas práticas de HTTP, como métodos e status adequados.

Exemplo: Ter endpoints como /api/clientes e /api/produtos, mas utilizar apenas o método POST para manipular esses recursos, sem ainda aplicar os métodos HTTP de maneira apropriada.

Nível 2 - Verbos HTTP​

Neste nível, a API começa a fazer uso dos verbos HTTP (GET, POST, PUT, DELETE) para representar operações nos recursos. Cada método tem um propósito específico (GET para leitura, POST para criação, PUT para atualização, DELETE para remoção), o que permite operações mais intuitivas e alinhadas com os padrões HTTP.

Exemplo:

  • GET /api/clientes – lista clientes
  • POST /api/clientes – cria um novo cliente
  • PUT /api/clientes/{id} – atualiza um cliente específico
  • DELETE /api/clientes/{id} – remove um cliente

Nesse nível, a API já oferece uma experiência mais RESTful, mas ainda carece de controles e navegação.

Nível 3 - HATEOAS (Hypermedia As The Engine Of Application State)​

O terceiro e último nível de maturidade é a adoção do HATEOAS (Hypermedia As The Engine Of Application State). Nesse nível, a API não só utiliza recursos e verbos HTTP, mas também fornece links e metadados adicionais que permitem ao cliente navegar pelos recursos dinamicamente. Ou seja, a API orienta o cliente sobre as ações disponíveis através de hipermídia (links), permitindo maior autonomia e descobribilidade.

Exemplo: Ao buscar informações sobre um cliente específico, a resposta pode incluir links para ações relacionadas, como /api/clientes/{id}/pedidos para acessar pedidos associados a um cliente ou /api/clientes/{id}/editar para atualizar os dados.