[pt-BR] O que é API REST?

Quando falamos de API REST, podemos entender inicialmente que o REST é algum tipo característica da API. Partindo desse pressuposto, vamos ver primeiro o que é API e quais as características a torna REST.

O que é API?

A sigla significa Application Programming Interface, e é um conjunto de rotinas e padrões que uma aplicação disponibiliza para que outras aplicações peguem essas informações. É responsável por estabelecer e facilitar a comunicação entre diversos tipos de serviços.

Na programação que utilizam APIs, costumamos ouvir muito o termo "consumir dados". Assim, podemos então fazer uma analogia muito interessante com um serviço de um garçom.

Vamos imaginar que temos um cliente que chama o garçom para pedir sua refeição em um restaurante:

O cliente faz o pedido
O garçom anota os pedidos e leva para cozinha
A cozinha prepara a refeição
O garçom traz a refeição ao cliente
O cliente consome sua refeição

Ou seja, podemos perceber que o garçom tem o papel de ser um mediador entre o cliente, que solicita, e a cozinha que prepara a refeição. O garçom que verifica o que o cliente quer e traz de volta pra ele consumir.

Se repararmos o próprio termo interface do nome API, ja deixa implícito esse papel de mediar, de estar entre alguma coisa.

Agora, trazendo pro mundo dev, vamos utilizar o cenário do Youtube:

O cliente é a página na web do Youtube e faz uma requisição (request), como por exemplo uma busca um vídeo
A API do Youtube verifica a solicitação e leva pro server
O server verifica se existe o vídeo e devolve uma resposta (response) para API
Se existir, a API traz o vídeo pra página exibi-lo
Se não existir, a API informa pra página que não foi encontrado nenhum vídeo.

O que é REST

A sigla significa Representational State Transfer e se traduzirmos, vamos perceber que tem a ver com uma transferência de estado, ou podemos dizer também, de dados.

Geralmente as transferência de dados na web utilizam o protocolo HTTP que, trazendo para a analogia do garçom, pode representar o bloco de notas que ele escreve o pedido. se quiser saber mais sobre HTTP, indico esse post.

O REST são algumas obrigações, regras ou padrões que vão estabelecer essa transferência de dados. Entretanto, caso a aplicação cumpra todos os requisitos do REST, ela torna-se uma aplicação RESTful. Veja abaixo, quais são esses padrões.

Padrões do REST para ser RESTful

🔹 Cliente-server

Separação entre cliente e servidor. Dessa forma podemos ter uma portabilidade de sistema, pois o cliente pode ser qualquer um. Exemplo: ReactJS e React Native consultando uma API do youtube.

🔹 Stateless

Cada pedido que eu fizer pro meu garçom, apenas ele precisa saber que esse pedido é pra mim e para minha mesa. Mas essas informações não precisam chegar na cozinha, para eles não faz diferença quem pediu. Além disso, o Cliente não precisa saber falar a língua da cozinha, nem a cozinha saber falar a língua do cliente. A responsabilidade em fazer essa comunicação é do garçom.

Ou seja, a API coleta as informações do usuário, verifica se está autenticado e apto a user os serviços para fazer a requisição. O servidor não irá receber nem armazenar nenhuma informação do usuário.

Além disso, nenhuma informação do pedido feito ao garçom pode faltar, senão a cozinha não irá preparar. Assim na aplicação, cada vez que o cliente faz uma requisição para a API, essas informações precisam ser completas que para serem devolvidas de maneira correta. Não seria nada legal o garçom levar a refeição na mesa errada, não é?

🔹 Cacheable

Dados em cache são informações guardadas para que a aplicação não precise solicitá-las toda vez que carregar. Isso traz mais rapidez pro sistema e ajuda na performance.

No caso do garçom, vamos supor que toda vez que você vai no restaurante, você pede a mesma coisa. Assim, seu pedido já está anotado, e quando você sentar na sua mesa, sua refeição já está lá! Caso você queira mudar de prato, o garçom limpará a mesa e você pede outra coisa.

Na API REST, as requisições podem ou não ser cacheadas, e isso DEVE ser declarado ou do lado do cliente ou do servidor.

Por exemplo, uma requisição GET deve ser cacheável por default - a não ser em situações específicas - e normalmente os browsers tratam todas as requisições GET como cacheáveis. A requisição POST não é cacheável por padrão, ou seja, deve ser informado de maneira explícita por um header "Expires", ou "Cache-Control". As respostas do PUT e DELETE não são cacheáveis.

Saiba mais sobre Cache, Expires e Cache-Control aqui.

🔹 Layered System

Quando o cliente acessa a um endpoint, ele não precisa saber da sua complexidade, de quais passos estão sendo necessários para o servidor responder a requisição ou quais outras camadas o servidor estará lidando para que a requisição seja respondida.

Na situação do restaurante, o cliente não quer saber qual caminho o garçom faz para chegar na cozinha, ou como a cozinha prepara seu prato. O cliente apenas quer receber exatamente o que ele pediu.

🔹 Uniform Interface

A aplicação deve seguir boas práticas de maneira consistente, constante e padronizada. Alguns exemplos de boas práticas está em escolher apenas um endpoint para cada fonte de dados (resource); usar padrão JSON como formato de escrita de mensagens; o uso correto dos verbos HTTP para comunicação clara e efetiva e manter o resource com informações suficientes para quem vai consumi-lo.

Será que na situação do restaurante, podemos dizer que o cliente deve escolher só os itens que estão no cardápio, e falar na mesma língua do garçom? Não sei se é a analogia ideal, mas acredito que deu pra entender!

🔹 Code on demand (opcional):

Essa caracteristica é opcional e ela se resume na possibilidade da aplicação pegar códigos executáveis, como o javascript por exemplo, e executar no lado do cliente para satisfazer alguma parte da sua aplicação. Como por exemplo, o cliente pode requisitar a sua API um widget para mostrar na tela.

Talvez seja semelhante a um cliente que pede ao garçom algum prato customizado, diferente do que normalmente o restaurante oferece.

API Verdadeiramente RESTful

Se por algum motivo uma API deixar de seguir um ou dois dos padrões aqui citados, ela ainda poderá ser considerada RESTful, só não será "verdadeiramente RESTful".

Consulte as duas fontes utilizadas para esse artigo: