Já consumiu uma API onde nada era intuitivo? Havia POST para obter dados. GET que faz UPDATE no banco. Saiba por que boas APIs seguem o padrão REST. Nesta série de artigos vamos abordar conceitos do REST e boas práticas na construção de API's RESTFul.

Se alguém disser "Mim dá um copo d'água pra mim" vai ser estranho. Certo? A frase está errada. Sonoramente falando é estranho.

O mesmo acontece quando é feito um POST em uma API para buscar um recurso. Não soa bem, é estranho.

Em ambos casos o receptor pode entender a mensagem, mas não estão de acordo com o padrão da linguagem.

Em linhas gerais e ignorando alguns conceitos. O HTTP assim como o português é um protocolo de comunicação. Seguir padrões seus padrões de escrita significa que você se esforça menos para entender.

Em um time, significa menos gasto de energia para resolver um problema. Torna o desenvolvimento ágil e mais eficiente.

Comunicar

O HTTP é um protocolo de comunicação. A definição de comunicação é: "Comunicação consiste na emissão, transmissão e recepção de uma mensagem. Através de métodos convencionais ou não. Por meio da fala ou da escrita, por sinais, signos ou símbolos"

O HTTP foi projetado para ser simples e legível por humanos. As mensagens podem ser lidas e entendidas. Utiliza uma estrutura bem definida, como verbos GET, POST ou substantivos como OPTIONS ou HEAD. A URL indica qual o recurso que deseja obter do servidor. O HEADER e o BODY são informações adicionais para o servidor processar a solicitação.

a communication protocol is a system of rules that allow two or more entities of a communications system to transmit information via any kind of variation of a physical quantity. The protocol defines the rules, syntax, semantics and synchronization of communication.
Wikipedia - Communication protocol

HTTP

Uma API e o Browser se comunicam através de mensagens HTTP. Existem dois tipos de mensagens HTTP, Requests e Responses, cada uma com seu próprio formato.

Uma request possui o seguinte formato:

Na imagem é possivel observar os seguintes elementos:

Method - É o método do HTTP. Abaixo há uma tabela com os métodos mais utilizados.
Path - É o endereço do resource que deseja obter.
Version of the protocol - Versão do protocolo HTTP. Atualmente o mais comum é o HTTP/1.1. Mas já há a versão 2 do HTTP. Inclusive o GRPC já suporta.
Headers - Os headers entregam informações adicionais para o server.
Body - É o conteúdo, geralmente é utilizado em conjunto com os verbos POST, PUT e PATCH.

Métodos mais utilizados:

HTTP Method	Descrição
OPTIONS	Busca os metodos http válidos e outras opções
GET	Busca um resource
HEAD	Busca apenas o header de um resource
PUT	Atualiza um resource
POST	Cria um resource
DELETE	Remove um resource
PATCH	Atualiza parcialmente um resource

O HTTP é connectionless, isso significa que para toda chamada haverá um RESPONSE. Mesmo que o client que chamou não esteja mais esperando a resposta. Por exemplo, quando o usuário fecha o browser. A response, possui o seguinte aspecto:

No response é possivel observar:

A versão do protocolo HTTP.
Status Code - Código de status. O código de status é separado por categorias.
- 2xx - Status de sucesso
- 3xx - Categoria de redirecionamento
- 4xx - Erro no Cliente
- 5xx - Erro no server
Status Message - A frente do Status Code virá uma breve descrição do que significa o Status Code.
Headers - Haverá informações para o Client, por exemplo o formato da resposta, se o conteúdo pode ser cacheado.
Body - Opcionalmente, dependendo do tipo de request, haverá no body o conteúdo da resposta.

O que é REST

REST é um estilo de arquitetura. Ele fornece padrões para a comunicação entre sistemas. REST não é um padrão exclusivo para HTTP. Embora as bases do REST e do HTTP sejam as mesmas.

Na arquitetura REST, os clientes enviam solicitações para recuperar ou modificar recursos e os servidores enviam respostas para essas solicitações.

Esse termo foi cunhado por Roy Fielding em sua tese de doutorado. No capitulo cinco em Architectural Styles and the Design of Network-based Software Architectures.

REST é o acrônimo de REpresentational State Transfer. Esse padrão é descrito em seis restrições.

Uniform Interface
Stateless
Cacheable
Client-server
Code on Demand (Opcional)

Não há uma definição formal para o que é RESTful. O que atualmente é mais aceito como explicação é: RESTFul é o termo utilizado para descrever API's HTTP que adotam o padrão REST.

Por que utilizar RESTFul?

APIs HTTP são os meios padrão de comunicação entre os sistemas. A internet é HTTP. Arquiteturas atuais como Microsserviços utilizam esse padrão em larga escala. Portanto respeitar o padrão do protocolo, permite que ele cumpra seu objetivo: Ser simples.

O Uncle Bob no seu livro Clean Code diz que a proporção entre ler código e fazer código é de 10 para 1.

Indeed, the ratio of time spent reading vs. writing is well over 10:1.
Martin, Robert C.. Clean Code (Robert C. Martin Series) . Pearson Education.

Já pensou se cada carro de cada montadora tivesse padrões diferente para dirigir? No carro da FIAT o acelerador ficasse no pé esquerdo? E da Ford fosse no meio. O volante do Peugeot fosse invertido, girar o volante pra direita fizesse com que o carro fosse para a esquerda.

A cada troca de carro seria um aprendizado completamente novo. Exigindo extremo esforço para aprender o novo padrão.

Aprender é um processo que gasta muita energia. Há estudos que explicam por que repetição é essencial para a vida humana. A humanidade não sobreviveria se tivesse que reaprender tudo todos os dias. Como escovar os dentes, andar e falar.

Ou seja, seguir um padrão significa diminuir o gasto de energia no processo de aprendizado. Padronizar significa menos energia.

Princípios do REST

Client-Server - Separar as responsabilidade do frontend do backend. Esse é um conceito bem comum. Separar o front do back há ganhos significativos em testes, escalabilidade com reflexos até na organização dos times dentro da empresa.

Stateless - O servidor não mantém estado. Cada solicitação do client deve conter informações necessárias para o server entender a solicitação. O estado da sessão é mantido inteiramente no client.

Cacheable - A resposta de uma solicitação deve implicitamente ou explicitamente informar se o dado pode ser mantido em cache ou não.
O cache deve ser mantido e gerenciado pelo Client.

Uniform interface - Este principio é definido por quatro restrições:

Identificar os recursos (URI)
Manipular recursos através de representações (Verbos HTTP).
Mensagens auto-descritivas, cada requisição deve conter informações suficientes para o server processar a informação.
HATEOAS - Hypermedia As The Engine Of Application State. Esta restrição diz que a response deve conter links de conteúdos relacionados ao resource. Por exemplo:
- GET http://api.jpproject.net/users/1
  Response:

{
	"userName": "bruno",
	"email": "bhdebrito@gmail.com",
	"phoneNumber": "11989500000",
	"name": "bruno",
	"links": [
		{
            "href": "10/claims",
            "rel": "claims",
            "type" : "GET"
        }
    ]
}

Neste exemplo repare que o response contém links para o resource claims. Dessa forma o controle de fluxo da aplicação é controlado através do server e não escrito na pedra pelo Frontend. Veja esse próximo exemplo de HATEOAS, onde é possivel saber as opções de Status de um resource.

{ 
  "userName": "bruno",
  “status”:”Active”,
  …
  “links”: [
    {“rel”:“block”, “href”:”/users/10/block”},
    {“rel”:“confirm-email”, “href”:”/users/10/confirm-email””}
  ]
}

Layered system - O sistema deve ter uma arquitetura em camadas. A camada acima não pode ver além da camada imediatamente abaixo dela.

Code on demand (opcional) - o REST permite que a funcionalidades do client seja estendida baixando e executando applets ou scripts.

Resources

O REST é Resource Based. Esse termo irei tratar com o nome em inglês pois é um item chave dentro do conceito.

Um Resource é a chave da abstração no REST. Um resource é qualquer coisa importante o suficiente para ser referenciado com um nome. O REST usa um URI (Uniform Resource Identifier) para identificar o resource. Resource é qualquer coisa que possa ter uma URI.

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource. A resource is a conceptual mapping to a set of entities, not the entity that corresponds to the mapping at any particular point in time.
Roy Fielding, CHAPTER 5 - Representational State Transfer (REST)

REST não limita a escolha da nomenclatura, qualquer coisa que seja indentificável e tenha uma URI está previsto pelo padrão. Escrevi um artigo dizendo que REST não é CRUD. Abordando em mais detalhes esse tópico.

Conclusão

Espero que você tenha entendido sobre REST e RESTFul. Minha consideração mais importante aqui é sobre Resources. Entender Resources é a chave para a criação de API's melhores.

Nos próximos posts, iremos abordar práticas de como construir API's REST.

Padrão REST