É muito comum ver APIs baseadas em arquitetura rest, mas seja por falta de conhecimento ou praticidade, não seguem à risca todas as restrições obrigatórias. A partir disso, temos um mapeamento, feito por Leonard Richardson, chamado Modelo de Maturidade de Richardson.

Nível 0 → Plain Old XML (POX). Nesse nível, o protocolo HTTP é utilizado apenas como transporte de dados, sem a utilização correta dos verbos e status. Geralmente, há apenas um único endpoint. Apesar do nome XML, também é possível utilizar JSON.

POST /salvarCliente 
    <Cliente>
         <Nome>Manoel da Silva</Nome>
         ...
  </Cliente>

Nesse nível, apenas um verbo é utilizado como tipo de operação: o POST. Todas as URLs criadas para obter dados, atualizar dados, inserir e deletar são chamadas utilizando o POST. Outro ponto interessante nesse nível é que há apenas uma única URL para acesso à API. Portanto, caso seja feita uma requisição para obter todos os usuários de um aplicativo, teríamos o seguinte exemplo:

Da mesma forma, caso a requisição realizada para essa API seja para inserir um novo cliente, a URL utilizada seria a mesma, alterando alguns parâmetros. No desenvolvimento, é responsabilidade do programador garantir que os processos requisitados sejam corretamente manipulados. Por exemplo, a URL para inserir usuários seria:

O problema de uma API nesse nível é que, para operações simples, é necessário criar muita documentação, pois além da falta de clareza sobre a estrutura e suas relações, os comandos são personalizados na URL.

Um outro problema constantemente encontrado, é a manipulação incorreta dos códigos de resposta do HTTP. Códigos e mensagens de erros são frequentemente manipuladas nas mensagens geradas pela aplicação, o que impede que elementos de gateway e proxy trabalhem de forma adequada.

GET /buscarCliente/1
HTTP/1.1 200 OK
<buscarCliente>
<status>CLIENTE NÃO ENCONTRADO</status> <codigo>404</codigo>
<buscarCliente>

Nivel 1 → As requisições são feitas para URIs que identificam recursos, porém, os verbos e códigos de status não são utilizados corretamente. O corpo e a resposta também são semelhantes. O tipo de procedimento ainda é definido no corpo.

Nesse nível, ainda é utilizado apenas um tipo de operação: o POST. Também é importante garantir que, nesse nível, os nomes dos recursos estejam no plural, sem letras maiúsculas e utilizando hífens para separação.

POST /clientes 
    <Cliente>
         <Nome>Manoel da Silva</Nome>
         ...
  </Cliente>

Nível 2 → Introduz o uso de verbos de acordo com a semântica e o protocolo HTTP. Os códigos são utilizados corretamente. Esse é o nível da maioria das aplicações do mercado. O formato do payload (XML/JSON) não interfere no nível.

POST /cliente
    <Cliente>
    <Nome>Manoel da Silva</Nome>
    ...
</Cliente>

Dessa forma, a API fica muito mais legível para manutenção, reduzindo seu custo e tornando-a mais fácil de ser consumida. Já se sabe, por exemplo, que ao fazer um GET é esperado o retorno de dados, e isso ajuda inclusive na performance da transferência de dados.

201 Created
 Location: /cliente/1

Nível 3 → HATEOAS (Hypertext as the engine of application state). Indica quais são as ações possíveis após uma requisição, juntamente com as URIs correspondentes. A ideia é ajudar os consumidores da API a descobrirem as funcionalidades e o fluxo da aplicação. A API retorna os links interligando o recurso com outros (ou até mesmo com ele mesmo), e existem especificações de como implementar os links com JSON.

GET /cliente/1
          HTTP/1.1 200 OK
          <Cliente>
              <Id>1</Id>
              <Nome>Manoel da Silva</Nome>
              <link rel="deletar" href="/cliente/1" />
              <link rel="notificar" href="/cliente/1/notificacao" />
          </Cliente>

Analisando todos os níveis de maturidade existentes e aplicando todas as práticas para atingi-los, é garantido que, ao construir uma API no nível 3 de maturidade, ela estará organizada, com os endpoints fáceis de serem compreendidos, recursos fáceis de serem encontrados, escalabilidade garantida e uma autodocumentação para seus recursos. Isso facilitará a vida dos usuários que irão consumi-la e dos desenvolvedores que a manterão.

A implementação do HATEOAS na API traz diversos benefícios:

1. Descoberta dinâmica de recursos: Com o HATEOAS, um cliente da API não precisa ter conhecimento prévio de todos os endpoints e recursos disponíveis. Em vez disso, ele pode começar a partir de um ponto de entrada conhecido (por exemplo, a URL raiz da API) e, a partir da resposta recebida, descobrir os recursos disponíveis e os links relacionados a eles. Isso permite uma experiência mais flexível e adaptável, uma vez que as alterações na API não exigem modificações nos clientes existentes.
2. Navegação simplificada: Os links fornecidos pela API permitem que os clientes naveguem facilmente entre os recursos relacionados, sem a necessidade de construir manualmente as URLs correspondentes. Por exemplo, um cliente pode obter um recurso "Cliente" e, a partir dos links fornecidos, navegar para a página de detalhes desse cliente, sua lista de pedidos ou qualquer outro recurso relacionado. Isso simplifica a interação com a API e reduz a carga cognitiva do desenvolvedor.
3. Evolução da API: Com o HATEOAS, a API pode evoluir e adicionar novos recursos sem interromper os clientes existentes. Se um novo recurso é introduzido e vinculado a partir das respostas da API, os clientes que entendem o padrão HATEOAS podem descobri-lo e começar a usá-lo. Isso promove uma arquitetura mais flexível e extensível, onde os clientes podem se adaptar a mudanças na API de forma dinâmica.

Exemplo: Suponha que uma API de e-commerce esteja retornando a seguinte resposta JSON para um recurso "Produto":

{
  "id": 123,
  "nome": "Camiseta",
  "preco": 29.99,
  "links": [
    {
      "rel": "self",
      "href": "/produtos/123"
    },
    {
      "rel": "pedidos",
      "href": "/produtos/123/pedidos"
    },
    {
      "rel": "avaliacoes",
      "href": "/produtos/123/avaliacoes"
    }
  ]
}

Nesse exemplo, os links são fornecidos no campo "links". O link "self" aponta para o próprio recurso "Produto" e os links "pedidos" e "avaliacoes" apontam para recursos relacionados. Um cliente que recebe essa resposta pode utilizar os links para navegar para esses recursos relacionados sem a necessidade de construir manualmente as URLs.

Portanto, o HATEOAS promove uma abordagem mais dinâmica e exploratória da API, permitindo que os clientes descubram recursos e interajam com eles de forma mais flexível e orientada por hipertexto.

É importante destacar que a adoção do HATEOAS pode adicionar complexidade à implementação da API e pode não ser necessário ou adequado para todos os casos de uso. Nem todos os projetos precisam ou se beneficiam de todos os níveis de maturidade. Portanto, é fundamental avaliar cuidadosamente as necessidades e metas do projeto antes de decidir em qual nível se concentrar.

Richardson Maturity Model

RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1

RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

RESTful Web APIs: Services for a Changing World

REST in Practice: Hypermedia and Systems Architecture