Trilha 10 · Internet e redes

APIs e REST

REST é a arquitetura que define como aplicativos se comunicam pela web usando os métodos e semântica do HTTP.

① Intuição

Uma interface para programas

Assim como um site tem uma interface para humanos (botões, formulários), uma API tem uma interface para programas. REST define que cada recurso (usuário, produto, pedido) tem uma URL própria, e os métodos HTTP (GET, POST, PUT, DELETE) expressam a intenção — ler, criar, atualizar, remover.

O que torna REST popular é a simplicidade: usa o HTTP que já existe, retorna JSON que todo browser entende, e não precisa de protocolo especial. Um curl na linha de comando já é suficiente para testar.

REST vs. outros paradigmas: GraphQL (uma única URL, o cliente descreve os dados que quer), gRPC (binário, mais eficiente, comum em microserviços), WebSockets (bidirecional, para tempo real). REST ainda domina APIs públicas por sua simplicidade e suporte universal.

② Visualização interativa

Explore uma API REST

Selecione um endpoint, veja o método e o path, e clique para enviar. A API mock responde com JSON real, status codes corretos e headers.

ENDPOINTS DISPONÍVEIS

RESPOSTA

Selecione um endpoint e clique Enviar

③ Explicação técnica

Convenções REST

# Convenções REST para um recurso "usuários"

GET    /api/usuarios        → lista todos             (200 OK)
GET    /api/usuarios/42     → busca por ID            (200 OK ou 404)
POST   /api/usuarios        → cria novo               (201 Created)
PUT    /api/usuarios/42     → substitui completamente (200 OK)
PATCH  /api/usuarios/42     → atualiza parcialmente   (200 OK)
DELETE /api/usuarios/42     → remove                  (204 No Content)

# Aninhamento — recursos relacionados
GET    /api/usuarios/42/posts     → posts do usuário 42
POST   /api/usuarios/42/posts     → cria post para o usuário 42

Estrutura de uma resposta bem projetada

# Resposta típica de uma API REST
HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": 42,
    "nome": "Ana Silva",
    "email": "[email protected]",
    "criadoEm": "2025-01-15T10:30:00Z"
  },
  "meta": { "requestId": "a3f8c2d1" }
}

Idempotência: GET, PUT e DELETE são idempotentes — chamar várias vezes tem o mesmo efeito que chamar uma vez. POST não é — criar o mesmo usuário duas vezes gera dois usuários. Isso é importante para retries em caso de falha de rede.

④ Projeto para programar

Crie sua primeira API REST

Mini projeto: implemente uma API de lista de tarefas (TODO) com 5 endpoints: listar, buscar por ID, criar, atualizar e deletar. Use um array em memória como banco de dados. Pode usar Express.js, FastAPI, ou qualquer framework.

Projeto principal: adicione paginação (?page=1&limit=10), filtro (?ativo=true), ordenação (?sort=nome&order=asc) e um header de autenticação (Authorization: Bearer token). Retorne erros com mensagens descritivas.

Desafio extra: escreva testes de integração para todos os endpoints usando pytest/jest: teste casos de sucesso, 404, dados inválidos (400) e autenticação falha (401).

⑤ Exercícios rápidos

Teste sua intuição

Seguindo as convenções REST, como se cria um novo usuário?

Qual é a diferença entre os métodos PUT e PATCH?

Qual status HTTP indica que um recurso foi criado com sucesso via POST?

⑥ Aplicações no mundo real

Onde você encontra isso

🐙

GitHub API

A API do GitHub é REST pura. GET /repos/usuário/repo/issues lista as issues. Você pode automatizar workflows inteiros com ela.

🔑

OAuth 2.0

"Login com Google" é uma API REST. Você redireciona para o Google, ele retorna um token, você usa o token em requests subsequentes.

🔄

Webhooks

REST invertido: em vez de você perguntar ao servidor se algo mudou (polling), o servidor te avisa via POST quando algo acontece.

📊

GraphQL

Uma alternativa ao REST: uma única URL, o cliente especifica exatamente os campos que quer. Evita over-fetching mas adiciona complexidade.

← Anterior: Como uma página carrega ✓ Concluir trilha Internet e redes