Você quer construir uma API REST, mas só encontra teoria abstrata sobre "transferência de estado" e "protocolos"? Vamos mudar isso. Este artigo é um tutorial prático. Vamos projetar, no papel, uma API REST real para um Gerenciador de Tarefas (To-Do List).
Ao final deste guia, você entenderá exatamente como estruturar URLs, usar os verbos HTTP corretos e desenhar respostas JSON profissionais.
O Cenário
Vamos criar uma API para gerenciar Tarefas.
Uma tarefa tem: id, titulo, descricao e concluida (verdadeiro/falso).
Passo 1: Definindo os Recursos (Substantivos)
No REST, pensamos em "Recursos" (Resources). O recurso principal aqui é a Tarefa. As URLs (Endpoints) devem representar esses recursos usando substantivos no plural.
- ✅ Certo:
/tarefas - ❌ Errado:
/pegarTarefas,/criarNovaTarefa
A URL identifica O QUE você está manipulando. O verbo HTTP identifica A AÇÃO.
Passo 2: Listar e Criar (A Coleção)
Como interagimos com a lista completa de tarefas?
Listar todas as tarefas
- Requisição:
GET /tarefas - Significado: "Ei servidor, me dê a lista completa."
- Resposta (200 OK):
[ { "id": 1, "titulo": "Comprar leite", "concluida": false }, { "id": 2, "titulo": "Lavar o carro", "concluida": true } ]
Criar uma nova tarefa
- Requisição:
POST /tarefas - Corpo (Body) enviado:
{ "titulo": "Estudar REST", "descricao": "Ler o tutorial completo" }
- Significado: "Ei servidor, adicione isso à coleção."
- Resposta (201 Created): O servidor deve retornar o objeto criado, agora com o ID gerado.
{ "id": 3, "titulo": "Estudar REST", "descricao": "Ler o tutorial completo", "concluida": false }
Passo 3: Manipulando um Item Específico
Agora queremos mexer na tarefa de ID 3.
Ler uma tarefa específica
- Requisição:
GET /tarefas/3 - Resposta (200 OK): Retorna apenas o objeto da tarefa 3.
- E se não existir?: Resposta 404 Not Found. (Muito importante usar o código de erro certo!).
Atualizar uma tarefa (Edição completa)
- Requisição:
PUT /tarefas/3 - Corpo:
{ "titulo": "Estudar API REST", "descricao": "Atualizado", "concluida": true }
- Nota: O PUT geralmente substitui o objeto todo. Se você enviar só o título, o resto pode ser apagado (depende da implementação, mas essa é a regra do PUT).
Atualizar parcialmente (PATCH)
Para mudar apenas o status para concluída, sem mandar o título de novo.
- Requisição:
PATCH /tarefas/3 - Corpo:
{ "concluida": true } - Significado: "Mude apenas este campo".
Deletar uma tarefa
- Requisição:
DELETE /tarefas/3 - Resposta (204 No Content): Sucesso, mas não tem nada para mostrar de volta.
Passo 4: Filtragem e Paginação
E se tivermos 10.000 tarefas? GET /tarefas travaria o app.
Usamos Query Parameters (aquilo depois do ?) para filtrar. Isso não muda a URL do recurso, apenas filtra a visualização dele.
- Paginação:
GET /tarefas?pagina=2&limite=10 - Filtro:
GET /tarefas?concluida=true(Me dê apenas as concluídas). - Busca:
GET /tarefas?busca=leite
Códigos de Status HTTP (O Feedback)
Uma API RESTful deve usar os códigos HTTP para dizer o que aconteceu. Não retorne sempre 200 com {"erro": "deu ruim"} no JSON. Isso quebra ferramentas de monitoramento.
- 200 OK: Deu certo.
- 201 Created: Criei o recurso com sucesso (usado em POST).
- 204 No Content: Deu certo, mas não tenho nada pra te mostrar (usado em DELETE).
- 400 Bad Request: Você mandou dados errados (ex: faltou o título).
- 401 Unauthorized: Quem é você? (Faltou token).
- 403 Forbidden: Eu sei quem é você, mas você não tem permissão para mexer nisso.
- 404 Not Found: Não achei.
- 500 Internal Server Error: O servidor explodiu (culpa do desenvolvedor do backend).
Conclusão
Projetar uma API REST é sobre organização e padronização. Ao seguir esse padrão (Substantivos na URL, Verbos HTTP na ação, Códigos de Status corretos), você cria uma API que qualquer desenvolvedor no mundo entende intuitivamente, sem precisar ler um manual de 500 páginas.
Agora é sua vez: pegue esse modelo e aplique no seu próximo projeto!