É 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:
- 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.
- 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.
- 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.
RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1
RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
Top comments (0)