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


“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 voltar um pouco no tempo.

vagas para desenvolvedores

O Gênesis da Internet

API e RESTful

² E a internet era sem forma e vazia; e havia dúvidas sobre a face de seus protocolos de comunicação;

³ 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.

esquema api restful

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.

>>Leitura Recomendada:
XML vs JSON: Entenda como fazer a melhor escolha

Web Services

Web Services

Um grande número de implementações começou a surgir. Entre eles, o XML-RPC, um web service criado em cima do protocolo HTTP, usado para transportar principalmente XML.

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. É agora que entramos no que interessa, o ponto onde a confusão começa: as Web Application Programming Interfaces (APIs) e o Representational State Transfer (REST).

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

O que é REST e RESTful?

REST e 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 do 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 já falamos hoje: 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.

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

Os padrões REST nem sempre importam

padrões REST

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.

vagas para programadores

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.

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

4.8
/
5
(
10

votes

)

O post Sua API não é RESTful: Entenda por quê apareceu primeiro em Geek Blog |.


Fonte Pixel
Data da Publicação Original: 26 March 2020 | 6:30 pm


You may also like

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *