Por que API RESTful é tão utilizado?

O que é API?

Application Programming Interface (API) ou Interface de Programação de Aplicações é um conjunto de rotinas e padrões disponibilizados por uma aplicação para que outras aplicações possam consumir seus recursos.
API é responsável por estabelecer comunicação entre dois serviços e intermediar a troca de informações.

API REST

O padrão de API mais comumente utilizado pela maioria dos dispositivos móveis e aplicativos da web para se comunicar com os servidores é chamado de REST ou REpresentational State Transfer.
REST é um conjunto de princípios e restrições necessários para a criação de um projeto com interfaces bem definidas que devem ser consideradas na troca de informações entre serviços da Web.
Esse estilo arquitetônico foi definido pelo cientista da computação Roy Fielding que anteriormente já havia trabalhado na criação do protocolo HTTP e definições da URI.

APIs REST que estiverem em conformidade com as seis restrições do padrão REST serão consideradas APIs RESTful:

• Arquitetura cliente-servidor: o modelo de arquitetura REST é composta por clientes, servidores e recursos. As requisições são feitas via protocolo HTTP com independência entre o cliente e o servidor.
• Sem monitoração de estado (Stateless): nenhum conteúdo do cliente é armazenado no servidor entre as requisições. Cada requisição ou REQUEST que o cliente faz para o servidor deve conter todas as informações necessárias para o servidor entender e gerar um RESPONSE de forma completa.
• Capacidade de cache: o armazenamento em cache pode eliminar algumas interações entre o cliente e o servidor e devem ser explícitas ao dizer se a requisição poderá ser armazenada pelo cliente.
• Sistema em camadas: O cliente acessa o endpoint de um recurso, sem precisar saber da complexidade necessária para o servidor responder a requisição ou quais outras camadas o servidor estará lidando para atender à requisição. Essas camadas podem oferecer recursos extras, como balanceamento de carga, caches compartilhados ou segurança.
• Código sob demanda (opcional): os servidores podem ampliar a funcionalidade de um cliente por meio da transferência de códigos executáveis. Apesar deste recurso ser pouco utilizado existe a possibilidade da aplicação obter códigos e executar no lado do cliente.
• Interface uniforme: Uma interface uniforme permite o desenvolvimento independente da aplicação entre usuário e servidor. Oferece uma comunicação padronizada entre o usuário e o software. A manipulação de recursos através de representações (como JSON ou XML) é uma das condições para o desenvolvimento de uma interface uniforme.

Efeitos arquiteturais REST

Os princípios e restrições implementados no estilo arquitetônico REST afetam importantes propriedades arquitetônicas de aplicações, incluindo:

• Performance em interações de componentes que podem ser o fator determinante no desempenho percebido pelo usuário e na eficiência da rede

• Escalabilidade permitindo o suporte de um grande número de componentes e interações entre componentes
• Simplicidade de uma interface uniforme
• Capacidade de modificação de componentes para atender às necessidades de mudança – mesmo enquanto o aplicativo está em execução
• Visibilidade da comunicação entre componentes pelos agentes de serviço
• Portabilidade de componentes movimentando o código do programa e os dados
• Confiabilidade na resistência à falha no nível do sistema na presença de falhas em componentes, conectores ou dados

Organização dos recursos

Uma API RESTful organiza recursos em um conjunto único de URIs (Uniform Resource Identificator).
URI é uma sequência única de caracteres que identifica um recurso lógico ou físico usado por tecnologias da web, podem ser usados para identificar qualquer coisa, incluindo objetos do mundo real, como pessoas e lugares, conceitos ou recursos de informação, como páginas da web, servidores e bancos de dados.

Os recursos devem ser agrupados por substantivos e não por verbos. A explicação para isso é que o URI deve referir-se a um recurso que é uma coisa (ou substantivo) em vez de se referir a uma ação (ou verbo) pois substantivos têm propriedades que os verbos não possuem – semelhantes aos atributos nos recursos.
Dessa forma um recurso de API para obter todos os pedidos deveria se chamar /pedidos e não /obterTodosPedidos.

Requisição

Um cliente interage com um recurso fazendo uma requisição ao endereço HTTP – endpoint do recurso.
A requisição ou REQUEST contém o URI do recurso que gostaríamos de acessar e é precedida por um verbo HTTP que informa ao servidor o que queremos fazer com o recurso.

Os verbos mais utilizados numa API RESTful são o POST, GET, PUT, DELETE eles permitem a implementação das operações básicas de CRUD, essenciais em praticamente todas as aplicações.

• Um verbo do tipo POST significa que queremos criar um novo recurso
• Um GET significa que queremos ler os dados sobre um recurso existente
• PUT é para atualizar um recurso existente
• e DELETE é para remover um recurso existente

Outros verbos HTTP importantes mas menos utilizados são:

• PATCH utilizado para atualizar partes de um recurso e não o recurso como um todo
• OPTIONS retorna os métodos HTTP suportados pelo servidor para a URI especificada
• TRACE devolve a mesma requisição enviada verificando se houve mudanças e/ou adições feitas por servidores intermediários
• CONNECT converte a requisição de conexão para um túnel TCP/IP transparente, geralmente para facilitar a comunicação criptografada com SSL (ou HTTPS) através de um proxy HTTP não criptografado

No corpo de uma requisição há um elemento opcional que chamamos de HTTP Request Body. O Request Body pode conter dados personalizados da requisição – payload – geralmente codificado no formato JSON, mas podendo ser codificado em outros formatos como por exemplo XML, HTML ou TEXTO.

Resposta

O servidor recebe a requisição, processa-a, e formata o resultado em uma resposta ou RESPONSE.
A primeira linha da resposta contém o código de status HTTP para dizer ao cliente o que aconteceu com a requisição.

Uma API RESTful bem implementada retorna os códigos de status HTTP adequados.

• Os códigos de nível 100 indicam que a requisição foi recebida e entendida. Essa resposta é despachada provisoriamente, enquanto o processamento da requisição continua.
• Os códigos de nível 200 indicam que a requisição foi bem-sucedida.
• Os códigos de nível 300 indicam que o cliente deve tomar medidas adicionais para completar a requisição.
• Os códigos de nível 400 indicam que algo estava errado com a nossa requisição.
  Por exemplo: A requisição possui sintaxe incorreta
• Os códigos de nível 500 indicam que algo deu errado no lado do servidor.
  Por exemplo: O serviço não estava disponível.

O corpo de resposta ou HTTP Response Body é opcional e pode conter os dados personalizados de resposta – payload – geralmente em formato JSON – também podendo ser codificado nos formatos XML, HTML ou TEXTO.

Idempotência

Um cliente poderia optar por tentar efetuar novamente uma requisição que tenha falhado, quando por exemplo retorna um código de status de nível 500. Dizemos “poderia optar por tentar efetuar novamente” porque algumas ações não são idempotentes ou possuem peculiaridades que requerem cuidado extra ao tentar novamente.
Quando uma API é idempotente significa que ao fazermos várias requisições idênticas ao mesmo recurso, teremos o mesmo resultado como resposta como se estivéssemos fazendo uma única requisição. Em outras palavras, um método idempotente não deveria possuir nenhum efeito colateral (exceto para manter estatísticas).

Os verbos HTTP implementados corretamente têm diferentes comportamentos em relação à Idempotência assim como em relação a outros princípios.

• O POST não é idempotente uma vez que cada nova requisição criará uma nova instância do recurso. Exemplo: um novo registro será criado no banco de dados a cada requisição. No entanto pode ser armazenado em cache para reutilização e melhoria de performance.
• O GET é por natureza idempotente, seguro e armazenável em cache.
• O PUT é idempotente e seguro.
• O DELETE é idempotente e seguro. Para ser idempotente, somente o estado atual do servidor deve ser considerado, o código de status retornado por cada requisição pode variar: a primeira chamada de um DELETE provavelmente retornar o código HTTP 200 (Sucesso), chamadas sucessivas provavelmente retornarão o código HTTP 404 (Não encontrado).

Stateless

Uma implementação REST é por definição STATELESS ou seja não preserva o estado das transações.
Isso significa que as duas partes na comunicação – o cliente e o servidor – não precisam armazenar nenhuma informação um do outro, e cada ciclo de requisição e resposta (REQUEST / RESPONSE) é completamente independente.
[*] Isso permite a criação de aplicações web mais confiáveis e mais fáceis de escalar.

Boas práticas

Use paginação

Se um endpoint de API retornar uma grande quantidade de dados, use paginação.
O uso de paginação permite a API trabalhar de forma mais eficiente com os dados na comunicação entre cliente e servidor, trafegando apenas o necessário.
Como o resultado será fragmentado no servidor, a resposta da mensagem trafegada fica bem menor, e por isso, o cliente consegue o resultado da requisição muito mais rápido, criando uma experiência agradável em termos de performance ao consumidor da API.
Como o consumo dos dados fica sob demanda, isso ajuda muito na escalabilidade vertical e horizontal da API.
[*] Essa prática permite o uso dos recursos de infraestrutura de forma mais inteligente.

Existem alguns esquemas para implementar a paginação, como por exemplo:

• Uso de cursor na paginação
• Uso de page e pagesize na paginação.
• Uso de offset e limit como técnica de paginação.

A paginação baseada em offset e limit é utilizada a partir de um deslocamento de registros.
Você especifica em offset a partir de qual registro você quer os dados, e em limit você especifica o limite de registros a serem retornados.
Como medida de boa prática, se “limit” e “offset” não forem especificados, o servidor deve assumir valores padrão sensatos.

Use versionamento

O controle de versão de uma API é muito importante por isso tome essa decisão já no início do seu projeto.
O controle de versão permite que uma implementação forneça compatibilidade com versões anteriores, de modo que, se introduzirmos alterações significativas de uma versão para outra, os consumidores da API terão tempo suficiente para passar para a próxima versão.

Existem algumas técnicas utilizadas para versionar APIs, por exemplo:

• Customização via Header
• Utilização de parâmetros via Querystring
• Versionamento por URI ou PATH

De longe o versionamento por URI é o mais utilizado e a maneira mais direta de fazer isso é prefixar a versão antes do recurso no URI.
Para identificar erros na mudança de versão de uma API você pode utilizar os seguintes códigos HTTP:

• 301 Moved permanently Indicando que o recurso foi movido permanentemente para outro URI
• 302 not found Indicando que o recurso solicitado está temporariamente localizado em outro local

Conclusão

A API RESTful é simples e eficaz quando aplicada de forma sensata.
Pode não ser a melhor escolha para todas as empresas e cenários, mas é simples e boa o suficiente e É EXATAMENTE POR ISSO QUE É AMPLAMENTE UTILIZADA.

Existem outras opções populares de padrão de API, como o GraphQL e gRPC e pretendo discuti-los e compará-los em outros artigos.

Se você gostou desse assunto, acompanhe nossas postagens, Youtube e redes sociais para ficar bem informado sobre tecnologias de desenvolvimento e TI.