Sua API não é RESTful: Entenda por quê

REST é a abreviatura de Representational State Transfer, que em português significa “Transferência de Estado Representacional”. REST é uma de arquitetura de software, que possui algumas boas práticas, definidas por Roy T. Fielding, para criação de aplicações web.

“Mas e a API, é RESTful?”

Todo desenvolvedor ao se deparar com uma API

A resposta é não!

Ok, talvez eu esteja exagerando um pouco.

Cada vez mais, com a evolução dos web services e a popularidade do “REST“, eu ouço essa pergunta e, em seguida, sua resposta: “É… Sim… Ta em REST“.

É então que eu mesmo me pergunto, será verdade?

A resposta curta: provavelmente não. Agora para entender melhor essa resposta, vamos entender alguns conceitos.

O que é o RESTful

Ao contrário do que muitos imaginam, REST não é necessariamente um protocolo de comunicação.

Criado por Roy T. Fielding em sua tese de Ph.D., REST é um estilo de arquitetura, ou seja, uma série de restrições que devem ser seguidas no processo de criação de um web service.

RESTful seria, então, a API que está de acordo com todas as restrições definidas por Roy.

E é aí que a maior parte das APIs RESTful caem por terra, pois dificilmente elas estão em conformidade com todas essas restrições, elas possuem diferentes graus de maturidade, conforme falaremos mais pra frente.

Restrições para uma API RESTful

Os principais critérios para uma API ser RESTful são:

• Uniform Interface;
• Stateless;
• Cacheable;
• Client-Server;
• Layered system.

Sem seguir todas estas restrições, sua API não será RESTful, será apenas mais uma implementação RPC em cima do protocolo HTTP.

Dentre todas elas, existe uma restrição que é geralmente menos atendida, a interface uniforme (Uniform interface). Mas, o que significa isso?

Alcançar uma interface uniforme significa atingir quatro critérios:

• Resource-based: Em contraposição ao comum RPC, REST tenta lidar com recursos invés de métodos. Caso você esteja criando um post chamando /posts/create?title=lorem você não está seguindo o padrão REST, devido ao tratamento de métodos na url. Nesse cenário, o ideal seria fazer uma chamada POST para a coleção de /posts.
• Manipulation of resources through representations: O cliente acessa os recursos através de uma representação (JSON, XML, etc.), que contenha informação suficiente para manipular este no servidor, desde que tenha permissão pra isso.
• Self-descriptive Messages: As respostas são auto-descritivas, incluindo informação suficiente para que o cliente saiba como utilizá-las. Usando HTTP, por exemplo, é necessário uma propriedade Content-Type incluída no cabeçalho para descrever que tipo de representação é utilizada.
• Hypermedia as the engine of application state (HATEOAS).

HATEOAS e RESTful

É aqui que se encontra a parte complicada. A restrição em que poucas APIs conseguem se enquadrar. O significado de “HATEOAS” denota muitas semelhanças com algo que falaremos a seguir: a World Wide Web.

Note que, a exploração das web pages na internet é feita no que podemos chamar de “caminhos“, temos um ponto de partida e a partir dele encontramos as demais páginas.

A mesma lógica se aplica as APIs RESTful. Basicamente, sua API deve ser um livro aberto, você não deve precisar de acesso a documentação para saber que para adicionar um usuário a coleção, precisará de uma requisição POST pra URL/users.

Deve ser possível descobrir todas as manipulações de seus recursos através da própria API.

Quais APIs que você conhece que fazem isso? Quais as que você consegue trabalhar sabendo apenas o domínio inicial (ponto de partida) e o protocolo?

Possuir uma documentação listando todos os recursos e ações disponíveis não é o problema, o problema está em quando você não recebe os hyperlinks necessários ao fazer uma requisição pra raiz da API, impedindo minha exploração dos dados e funcionalidades.

Ou seja, isso indica que: sua API provavelmente não é RESTful. E está tudo bem.

Qual a diferença entre API REST e RESTful

Como explicado, para que uma API seja denominada RESTful, ela precisa de algumas propriedades específicas.

Então a diferença entre API REST e RESTful é somente o cumprimento das exigências que a arquitetura exige.

Podemos dizer que uma Representational State Transfer (REST) é uma abstração da arquitetura da World Wide Web. É um estilo arquitetural que consiste de um conjunto coordenado de restrições aplicadas a componentes, conectores e elementos de dados dentro de um sistema.

O REST ignora os detalhes da implementação de componente e a sintaxe de protocolo com o objetivo de focar nos papéis dos componentes, nas restrições sobre sua interação com outros componentes e na sua interpretação de elementos de dados significantes.

Caso tenha ficado alguma dúvida, o vídeo abaixo explica a diferença de REST x RESTful!

Entendido essa diferença e os conceitos, vamos para o contexto.

O Gênesis da Internet

E disse Tim Bernes-Lee: “Que haja a World Wide Web“.

Era 1989, embora a internet já existisse, seu potencial ainda não era aproveitado.

Foi criada, então, a World Wide Web, um sistema de informação que, além de trazer a identificação única de recursos (Uniform Resource Locators – URL), possibilitou a ligação destes através de hipertextos.

Os recursos disponíveis na Web podem ser de qualquer tipo de mídia, porém, as chamadas web pages eram escritas em um formato específico: o Hypertext Markup Language (HTML), linguagem de marcação que possibilita a ligação entre diferentes páginas através dos hiperlinks, criando, então, a verdadeira teia de páginas na internet.

Mas, pra isso tudo funcionar, era necessário um protocolo de comunicação.

Foi quando surgiu o Hypertext Transfer Protocol (HTTP), muito conhecido hoje em dia.

O interessante é que, na época, ele só era usado para transportar HTML. Bem diferente de hoje em dia, não é mesmo?

Até então, eram usados outros protocolos de comunicação para transportar diferentes tipos de dados através do Remote Procedure Call (RPC), onde eram requisitados serviços de outras máquinas a fim de conseguir algum recurso em uma rede sem saber, necessariamente, detalhes dessa rede.

Foi em 1998 que Dave Winer resolveu juntar a Web com os Services existentes, criando os webservices. Sendo o primeiro deles, o XML-RPC.

O que é um Web Service e como funciona

Um Web service é uma tecnologia que permite a comunicação independente entre aplicações, sem depender de linguagens ou sistemas operacionais.

No geral, essa comunicação acontece através de arquivos em formato XML. Sendo assim, independente da linguagem, tudo é traduzido para XML. Entre eles, o XML-RPC, criado em cima do protocolo HTTP.

Depois de certo tempo, o XML-RPC foi batizado com outro nome: Simple Object Access Protocol (SOAP).

Sendo classificado, então, como um protocolo de comunicação que fazia uso, em seus protocolos de mais baixo nível, do HTTP.

Este protocolo era poderoso em termos de capacidade de exposição dos dados aos interessados. Mas, apesar do nome, não tem nada de simples.

Em pouco tempo, o SOAP tornou-se um padrão de mercado e era utilizado majoritariamente entre as organizações.

Mas, precisávamos de uma solução melhor e mais simples. Foi aí que entraram as Web Application Programming Interfaces (APIs) e o Representational State Transfer (REST).

Contexto entendido? Agora vem comigo para a sacada desse artigo.

Algoritmos de recomendação: o que são e como implementá-los?

Os padrões REST nem sempre importam

Não importa se sua API é RESTful ou não. Assim como boa parte das decisões de arquitetura existentes, elas nem sempre atendem o problema da melhor maneira.

Talvez você esteja desenvolvendo uma API interna, onde você tem controle tanto do cliente quanto do servidor. Nesse caso, a parte da descoberta pode não trazer tanto retorno.

A decisão é sua. Ainda existem muitas coisas a serem aproveitadas na arquitetura REST e, apesar da sua API não atender todos os requisitos, talvez ela esteja de acordo em muitos pontos, aqui que entramos em algo chamado Richardson Maturity Model.

XML vs JSON: Entenda como fazer a melhor escolha

Richardson Maturity Model

Como dito anteriormente, as APIs possuem diferentes graus de maturidade em relação às regras mais importantes da arquitetura REST.

Existe uma maneira simples de definir esse grau: o Richardson Maturity Model.

Esta maneira supõe diversas restrições de antemão, visto que algumas delas são intrínsecas a arquitetura da web, ainda assim, pode ser uma boa base para classificar sua API.

O modelo possui 4 níveis de maturidade (sendo 0 uma API que não atenda nenhuma das regras), os outros 3 são:

1. Recursos: A partir do momento em que seja possível fazer requisições de diferentes recursos em diferentes endpoints. Sem a necessidade dos chamados query parameters.
2. Verbos HTTP: Aqui, os diferentes métodos HTTP são colocados em prática, em contraposição ao uso quase exclusivo do POST no protocolo SOAP. Além disso, cada verbo possui sua utilidade específica: PUT para atualizar, DELETE para excluir, GET para adquirir e POST para criar. Em alguns casos o PATCH também é utilizado.
3. Hypermedia: Os recursos passam a possuir links para recursos relacionados, além de links para realizar ações em cima dessas coleções, a partir desse ponto, a API se auto-documenta e possibilita a funcionalidade de descoberta.

Cada nível é uma condição para o próximo, ou seja, para uma API possuir nível 3, ela precisa primeiro chegar ao nível 2 e 1. Você pode saber mais sobre o Modelo de Maturidade Richardson clicando aqui.

Ficou alguma dúvida? Algum ponto que não abordamos que seria interessante para você? Comente aqui embaixo que iremos responder.

Esse artigo foi escrito pela equipe da empresa júnior da UFSC, Pixel.