REST, APIs e RESTful APIs

6 min readApr 20, 2022

Diferente do que o próprio nome sugere, REST não tem nada a ver com algum tipo de estado de “descanso” de algo, trata-se de uma sigla para: Representational State Transfer, ou do português Transferência de Estado Representacional.

Durante minhas pesquisas eu vi diversas classificações sobre o que é REST, mas a nomenclatura que fez mais sentido para mim foi: Design de Arquitetura, ou seja, um estilo ou conjunto de normas para estruturar a arquitetura de uma interface de programação de aplicação (APIs).

Mas o que são APIs ?

“Application Programming Interface”, traduzindo para o português: “Interface de Programação de Aplicativos”, explicando de uma forma bem ignorante, são normas de desenvolvimento para realizar a integração entre sistemas em um modelo provedor e consumidores.

Em um post anterior eu comentei que o protocolo HTTP serve para padronizar a forma como os dados trafegam de uma ponta à outra em uma comunicação TCP/IP. Mas quanto menos abstraímos esse conceito, começamos a compreender que essas “pontas” tratam-se de sistemas enviando pedidos e esperando uma resposta. Mas peraí, como é que esses sistemas sabem o que é que vai vir da outra ponta ? Como é que o meu sistema vai estar preparado para receber e tratar essas informações ?

É justamente esse o papel das APIs, permitir que cada sistema de cada extremo da comunicação esteja preparado para receber e processar essas informações, sem necessariamente adotar as regras de negócios do provedor destes mesmos dados. Fornecendo um contrato em comum para que aplicações ou serviços de domínios e linguagens diferentes consigam se comunicar. Funcionando como uma espécie de ponte, entre uma aplicação em outra.

De onde veio o termo REST ?

O termo REST apareceu pela primeira vez em um artigo do Roy Fieldings (um dos criadores do protocolo HTTP), com o título de “Architectural Styles and the Design of Network-based Software Architectures“, em português “Estilos arquitetônicos e o design de arquiteturas de software baseadas em rede”. Nesse artigo surgiram os primeiro conceitos sobre REST e o que são APIs RESTful, na qual vou falar mais à frente.

O intuito da criação de um estilo de arquitetura para a comunicação entre serviços o web, permite que aplicações que seguem um modelo de comunicação Stateless, utilizem dos recursos e métodos do protocolo HTTP para realizar uma espécie de “comunicação padronizada” afim de manipular o estado do que chamavam antigamente de “modelo de objeto HTTP”. Essa valorização semântica é o que diferencia uma arquitetura REST das outras arquiteturas web, resultando em interfaces uniformes.

Uma série de diretrizes que visam uma arquitetura mais rápida, leve, altamente compreensível e facilmente escalável.

Padrão de comunicação em uma arquitetura REST (protocolo HTTP)

Discutimos mais acima, sobre REST ser um conjunto de normas arquiteturais e não um padrão ou protocolo. Só que também vimos que esse conjunto de restrições ou normas, andam lado a lado com o protocolo HTTP.

Junto com os verbos dos métodos HTTP e as regras de desenvolvimento, a semântica da API torna-se muito mais clara, de forma que o consumidor que a implementa não precise acessar a documentação para saber que para adicionar um produto novo, será necessário bater no endpoint /produtos utilizando o POST (método HTTP).

Esse “auto entendimento” de saber onde requisitar tal informação, deve-se a um dos principais princípios REST, conhecido como Sintaxe Universal para Identificar os Recursos, implicando que cada recurso é conduzido apenas pela sua URI

Os métodos HTTP tem uma forte ligação com as operações CRUD, os mais comuns de se ver em aplicações REST são:

GET: Solicita a representação de uma entidade/documento/recurso específico e deve retornar apenas dados.
POST: Submete uma entidade/documento/recursoespecífica a um recurso específico, usado para enviar dados de entrada no servidor.
DELETE: Utilizada para remover uma entidade/documento/recurso do servidor.
PUT: Atualiza o estado e ou valor, de uma entidade/documento/recurso já existente.
PATCH: Representa a modificação parcial em uma entidade/documento/recurso

Juntamente com a semântica dos endpoints e métodos HTTP, aplicações REST buscam responder com um status coerente com a ação, por exemplo:

Se uma entidade foi requisitada para ser criada em um determinado domínio, e o servidor responde um body com o id dessa entidade confirmando a sua criação, então na resposta HTTP do servidor deve conter o código de Status: 201 que representa a criação de um objeto ou recurso com sucesso.

Seguem alguns status codes mais utilizados:

200 — OK: Requisição bem sucedida, mas o significado pode variar a depender do método HTTP utilizado;
201 — CREATED: A requisição foi bem sucedida e um novo recurso foi criado como resultado;
204 — NO CONTENT: Geralmente é usado para representar que um recurso foi deletado com sucesso quando a requisição é feita com o método DELETE;
400 — BAD REQUEST: ocorreu algum erro na requisição (podem existir inumeras causas);
401 — UNAUTHORIZED: Mesmo parecendo ser referente a permissão, simboliza a “não autenticação” do cliente no servidor, bem comum em respostas para tokens expirados;
403 — FORBIDDEN: O cliente da requisição não tem permissões para acessar o conteúdo por meio daquele endereço;
404 — NOT FOUND: Endpoint/endereço ou recurso não encontrado no servidor;
500 — INTERNAL SERVER ERROR: Representa erros internos do servidor. =D

Falamos sobre as reações do servidor com base nos métodos e status de resposta HTTP, mas ainda temos um ponto em aberto:

“Como enviamos e visualizamos esse objeto ou recurso solicitado para o servidor ? ”

Bem simples, a representação do estado do objeto ou recurso, tanto para quem envia quanto para quem recebe a informação, pertencem ao mesmo formato. Esses formato que é definido e esperado pelo servidor dentro do cabeçalho da requisição, na propriedade Content/Type , dentre os formatos válidos, os mais comuns de se ver são: JSON, XML, XLT, PHP e etc…

O mais utilizado é o formato JSON, ou Javascript Object Notation, por ser independente de outras linguagens e ser facilmente compreensível por humanos e máquinas. Segue o exemplo de um body response no formato JSON:

HTTP/2.0 200 OK
Content-Type: application/json{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "A cool name",
      "body": "A crazy description",
      "created": "2022-02-22T13:56:19.000Z",
      "updated": "2022-02-22T13:56:18.000Z"
    },
    "anotherObject": {
      "anyTypeProperty": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }
}

RESTful APIs e suas restrições

Quando eu comecei a estudar sobre desenvolvimento de software eu ouvia essas duas palavras para cima e para baixo: REST e RESTful. E sempre imaginei que RESTful fosse um outro design arquitetural derivado dos conceitos e princípios do REST. Acredito que boa parte das pessoas que estão iniciando na área deva fazer alguma confusão desse tipo com esses dois termos. Caso você seja uma dessas pessoas eu posso te resumir a diferença em 10 palavras: “REST é o design arquitetural, RESTful é uma API de acordo com todas as normas REST”, pronto, da forma mais simples e direta possível.

Digamos que essa normas funcionam como uma espécie de “critérios de aceite” para que uma API receba o título de RESTful. Isso implica que uma RESTful API:

Precisa funcionar numa estrutura cliente-servidor (Client-Server) :
Ser um sistema em camadas (Layered System) : Camadas com responsabilidades e abstrações diferentes, a camada de cima não pode conhecer o que está além da primeira camada abaixo dela.
O servidor deve trabalhar em um modelo Stateless;
Possui uma interface uniforme (Uniform Interface) : Definida por meio de quatro elementos de interface:
— Identificação de recursos, URI;
— Manipulação de recursos através de representações, verbos HTTP;
— Mensagens Auto descritivas;
— Hipermídia como máquina de estados da aplicação, a resposta HTTP deve conter links referentes ao contexto do recurso consultado;
Suportar o armazenamento em cache (Cacheable) : Define que a resposta HTTP deve de alguma forma informar se o dado retornado pode ou não ser armazenado em cache.