O que uma boa API Rest deve ter e porquê?

Mas antes, o que é REST?

REST é um tipo de arquitetura web desenvolvido por Roy Thomas Fielding, em seus estudos ele procurou entender os principais problemas da web e como poderia ajudar a melhorar a performance, escalabilidade e demais problemas que haviam relacionados ao tema, isso lá em 2000.

Nos seus estudos, ele consta que o principal problema da www era:

> Como compartilhar informações com todo mundo de forma estruturada sendo que em cada terminal de comunicação (tanto lado do cliente como do servidor) haviam informações de formas variadas (textos, imagens, vídeos, etc), tamanhos variados e sistemas operacionais diversos (linux, windows, etc)?

Isso era (e ainda é) um questionamento muito importante tendo em vista que a web é cada dia mais utilizada e deveria ter a possibilidade de transitar qualquer tipo de informação de forma rápida, eficiente e escalável.

Sendo assim, Roy Fielding, se embasando em arquiteturas já existentes, elaborou a arquitetura REST de comunicação web.

REST é o acrônomo de Representational State Transfer ou, do português, Transferência Representacional de Estado (tradução livre).

Características da arquitetura REST

1. Responsabilidades na relação cliente-servidor (client-server) são separadas, isso significa que a preocupação da parte visual fica com o cliente enquanto que o servidor fica com o lado de armazenamento/recuperação de dados, assim temos uma distribuição de tarefas muito melhor e nem dos lados fica sobrecarregado.

2. Isso é um ponto interessante, pois, automaticamente, auxilia na simplicidade do processo de comunicação (uma vez que o lado do servidor é independente do que ocorre do lado do cliente) e melhora a escalabilidade.

3. A comunicação é STATELESS, ou seja, ela não guarda em memória as requisições e respostas dessas requisições. Isso auxilia na simplicidade da comunicação, uma vez que, para que a requisição tenha a sua resposta, ela deve vir completa e, em caso de erro, fica fácil de visualizar onde está o erro.

4. Também é escalável, exatamente por conta dessa simplicidade da comunicação, ou seja, o servidor não precisa gerenciar arquivos em memória (o que atrapalharia muito performance, por exemplo) e é confiável, pois, caso não siga o protocolo, a comunicação dará erro

5. É CACHEABLE, ou seja, mantém um cache (uma memória de respostas de determinadas requisições já feitas anteriormente) para retorno mais rápido caso. Isso serve para corrigir um ponto de performance da questão do stateless, porque, sem o recurso de cache, a arquitetura sempre terá que recuperar a mesma resposta do zero, sendo que ela poderia ter uma performance melhor se já tivesse a resposta pronta.

6. Mas como o cache não entra em conflito com o stateless? Simples, o stateless significa que a aplicação não guarda nenhum estado de requisição, login, etc, entretanto, com o cache, já temos uma resposta pronta caso a requisição feita seja alguma já feita anteriormente.

7. A arquitetura REST tem uma interface uniforme, ou seja, qualquer aplicação que siga essa arquitetura, se comunicará sempre da mesma forma com as especificações que serão melhor faladas mais a frente.

Como o REST transita as informações?

Diferentemente do que muita gente acha, a arquitetura REST NÃO transita o objeto (imagem, arquivo, audio, etc) em si, mas sim uma representação dele (eis aí o nome de transferência representacional de estado). Ela segue a mesma ideia de encapsulamento da informação que se vê no mundo da programação orientada a objetos, onde temos os getters e setters.

fonte: Roy Fielding (https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)

Nessa arquitetura, quando queremos ter acesso à uma imagem, por exemplo, a chamamos de recurso, ou seja, qualquer item que se queira ter acesso (receber ou enviar) chamamos de recurso. Esse recurso terá um identificador (aqui é onde entra a idea do getter), o identificador será uma URI. Quando ser acessar o identificador, aí sim temos o acesso ao recurso, no nosso exemplo teremos acesso à imagem.

A representação é a forma como esse recurso será apresentado, no caso, no formato metadata (chave e valor), atualmente é muito comum ser representado no formato JSON.

E, por fim, o control data especifica o motivo da comunicação e como ela ocorre, ou seja, o que a requisição quer e como ela precisa.

Conclusão

Entendendo um pouco sobre os problemas da web e como queremos fazer a comunicação de forma prática, escalável e mais padronizada, faz muito sentido seguirmos o padrão REST no momento de construirmos uma API.