API REST como funciona: guia completo e didático

Uma API REST (Representational State Transfer) é um estilo de arquitetura que define como dois sistemas podem se comunicar pela internet usando o protocolo HTTP. Em vez de criar uma nova camada de comunicação, ela aproveita os verbos e códigos que o HTTP já oferece. Isso torna a integração entre aplicações web, mobile e serviços de terceiros muito mais simples e padronizada.

O que uma API REST faz?

Uma API REST permite que um sistema acesse ou manipule recursos de outro sistema. Esses recursos podem ser dados de um usuário, uma lista de produtos, o status de um pedido, entre outros. A comunicação acontece por meio de requisições HTTP que seguem um conjunto de regras chamado RESTful. Na prática, a API REST atua como um intermediário: o cliente (seu app ou site) faz uma solicitação, e o servidor responde com os dados solicitados, geralmente em formato JSON ou XML.

Quais são as regras de uma API REST?

Para ser considerada RESTful, uma API precisa seguir alguns princípios:

• Interface uniforme: cada recurso (ex.: um usuário) tem um identificador único, como /usuarios/123. As operações são definidas por métodos HTTP.
• Sem estado (stateless): cada requisição deve conter todas as informações necessárias para ser compreendida. O servidor não armazena o estado do cliente entre requisições.
• Cacheável: as respostas podem ser marcadas como cacheáveis ou não, melhorando a performance.
• Cliente-servidor: separa a interface do usuário do armazenamento de dados, permitindo que evoluam de forma independente.
• Camadas: a arquitetura pode ter intermediários (proxies, gateways) que não interferem na comunicação.

O que é um método REST em uma API?

Os métodos REST são os verbos HTTP que indicam qual ação deve ser executada sobre um recurso. Os mais comuns são:

• GET: lê ou recupera um recurso. Exemplo: GET /usuarios retorna a lista de usuários.
• POST: cria um novo recurso. Exemplo: POST /usuarios com dados no corpo da requisição adiciona um novo usuário.
• PUT: atualiza um recurso existente por completo. Exemplo: PUT /usuarios/123 substitui todos os dados do usuário 123.
• PATCH: atualiza parcialmente um recurso. Exemplo: PATCH /usuarios/123 altera apenas o e-mail.
• DELETE: remove um recurso. Exemplo: DELETE /usuarios/123 exclui o usuário 123.

Cada método tem um propósito específico e, quando combinado com a URL correta, forma a base da comunicação REST.

Como uma API REST se diferencia de outras APIs?

Diferente de estilos mais antigos, como SOAP (que usa XML complexo e requer mais configuração), a API REST é mais leve e flexível. Ela não impõe um formato rígido de mensagem, você pode usar JSON, XML, ou até texto puro. Além disso, por ser stateless, ela escala melhor: cada requisição é independente, o que facilita o balanceamento de carga em servidores.

Exemplo prático de como uma API REST funciona

Imagine um aplicativo de previsão do tempo. Quando você abre o app, ele faz uma requisição GET para https://api.climatempo.com.br/v1/cidades/1234. O servidor da Climatempo processa a requisição, consulta o banco de dados e retorna um JSON com a temperatura, umidade e previsão para aquela cidade. O app então exibe esses dados para você. Tudo isso acontece em milissegundos, sem que você precise saber como o servidor interno funciona.

FAQ: Perguntas frequentes sobre API REST

O que significa REST?

REST é a sigla para Representational State Transfer, ou Transferência de Estado Representacional. Foi proposto por Roy Fielding em 2000 como um estilo arquitetural para sistemas distribuídos, baseado no protocolo HTTP.

Toda API que usa HTTP é REST?

Nem toda. Para ser RESTful, a API precisa seguir os princípios REST, como stateless, interface uniforme e uso correto dos métodos HTTP. Muitas APIs que usam HTTP são apenas "baseadas em HTTP", sem seguir todas as regras.

API REST e API RESTful são a mesma coisa?

Sim, os termos são usados como sinônimos. "REST" se refere ao estilo arquitetural; "RESTful" é o adjetivo para uma API que implementa corretamente esse estilo.

Quais formatos de dados uma API REST pode usar?

O mais comum é JSON, por ser leve e fácil de ler. XML também é suportado, mas perdeu espaço. Alguns serviços usam YAML ou até texto simples, dependendo do caso.

Uma API REST precisa de autenticação?

Depende do recurso. APIs públicas podem ser abertas, mas a maioria exige algum tipo de autenticação, como chave de API (API key), token JWT ou OAuth, para controlar quem acessa os dados.

Como saber se uma API é RESTful?

Verifique se ela usa URLs para identificar recursos, métodos HTTP para ações, é stateless e retorna códigos de status HTTP adequados (200 para sucesso, 404 para não encontrado, 201 para criação, etc.).