Introdução

Atire a primeira pedra quem nunca entrou em uma empresa, onde sua primeira atividade é adicionar uma nova feature na tal "API REST", mas ao abrir o código do projeto você se depara com um:

POST /client/infos/update-infos

Ou pior

POST /client/infos/delete-infos

É triste mais é a realidade, existem vários sistemas que se consideram REST, mas não são.

Passando pelas leis do REST

Quando falamos que uma API é REST, significa que desenvolvemos uma aplicação de transporte de informações que utiliza HTTP, porém com regras claras criadas por Roy Fielding.
Caso você siga TODAS a risca, pode ser considerada uma API RESTful.

Fiz uma tabelinha com as leis do REST:

Caso você ainda tenha dúvida sobre elas, recomendo fortemente, ler o próprio artigo do Roy Fielding.

Medindo a maturidade de sua API

Beleza, já sabemos quais regras que devemos implementar para de fato termos uma API RESTful, mas o que você vai perceber que no dia a dia de trabalho, raramente vai encontrar tudo isso implantado.
Normalmente não vemos por conta da relação tempo x custo, por conta disso quase sempre você irá encontrar outro tipo de padrão no mercado.

Mas, como podemos medir se a API que estamos criando, ou atuando, é REST?

Para isso o desenvolvedor Leonard Richardson, criou o RMM (Richardson Maturity Model), dessa forma dividimos alguns padrões do REST em 3 níveis.

Vou explicar cada nível para vocês.

Os 3 níveis para a glória REST

Nível 0: POX

Nesse nível, consideramos que API só serve mesmo como transporte de informação, não utiliza corretamente URI, verbos HTTP, HATEOAS e status code, nem possui padrão de formato representacional (JSON, XML e etc).

Podendo ter casos, onde a mensagem de erro nos retorna código 200, e vem no corpo da resposta, o erro que pode ter ocorrido no serviço.

HTTP/1.1 200 OK
[headers]

<compraDeProutosErro>
  <produto descricao="teclado mecânico" id="0293"/>
  <cliente cpf = "xxxxxxxxxxxxx"/>
  <reason>Produto esgotado.</reason>
</compraDeProutosErro>

Nível 1: Recursos

Nesse ponto sua API já está trabalhando corretamente com URI para manipular seus recursos, mas ainda não implementa verbos HTTP, HATEOAS e status code corretamente.

Aqui já começa a ser comum de encontrar por aí, já encontrei várias dessas em alguns projetos de mercado.

Continuam utilizando os verbos GET e POST para realizar consultas e operações.

Nível 2: Verbos HTTP

Finalmente começamos a encontrar o uso correto das URI, verbos HTTP e status code. Para o padrão que encontramos, aqui existe um debate muito discutido.

Alguns programadores não consideram o nível 2 como uma API REST, já que não há o HATEOAS, já outros consideram. Com minha experiência e minha opinião, aqui coloco que sim, já considero uma API REST a partir desse ponto.

Nível 3: HATEOAS

HATEOAS, significa Hypertext As The Engine Of Application State, um nome feio e enorme, praticamente chamamos de Hypermedia Controls.

Para entender, vamos a um exemplo, imagine uma página HTML, onde temos diversos links que chamam para outros HTML. Fica vísivel qual caminho podemos adotar para vermos, por exemplo, informações de um produto, da conta e etc.

A mesma coisa vale para a API, quando realizamos uma requisição, no retorno dela, deve ter alguns endpoints para ajudar ao usuário a explorar outros recursos.

Vamos a um exemplo, imagine que quero consultar um produto:

GET /produtos/872

Como retorno HATOEAS, deveríamos ter uma resposta parecida com isso:

HTTP/1.1 200 OK

{
   "id":89,
   "nome":"Mouse ergonômico"
   "preco": 430,
   "links": {
      "fornecedor": "/fornecedores/23"
   }
}

Onde, além do retorno de uma consulta sobre um determinado produto, adicionamos um link para a URI de fornecedores, para dar um caminho e até mesmo uma ajuda para o usuário ir explorando os recursos da API.

Conclusão

É muito raro encontrarmos uma aplicação que implemente o nível 3, por isso muitos desenvolvedores consideram o nível 2 como uma API REST.

Perguntinha do artigo para refletir!

Você já trabalhou com mais APIs nível 3 ou 2?

Espero que tenha ficado claro e te ajude a medir a maturidade de suas API que virão pela frente.

Obrigado pelo seu tempo.
Compartilhem com seus colegas de estudo/trabalho.
Me acompanhem em minhas redes sociais:

• GitHub
• LinkedIn
• Twitter
• YouTube

Até a próxima!