APIs REST · 2026-07-11

APIs REST com Agentes de IA: Tutorial Completo com Claude Code e Codex

Tutorial completo para desenvolver APIs REST com agentes de IA usando Claude Code e Codex. Aprenda a criar rotas, models, autenticação e testes com backend agentes IA.

Criar uma API REST completa é uma das tarefas mais recorrentes no desenvolvimento de software moderno. Quando o assunto é APIs REST agentes IA, a combinação de Claude Code e Codex pode transformar dias de trabalho em horas. Este tutorial mostra, passo a passo, como desenvolver uma API REST completa — roteamento, banco de dados, autenticação e testes — usando agentes de IA como seus assistentes de codificação. Você vai aprender a criar API com Claude Code para estruturar rotas e controllers, usar API REST Codex para gerar models e camada de banco, e integrar tudo em um pipeline de desenvolvimento acelerado.

Sumário

Cenário: o que vamos construir

Vamos desenvolver o backend de um sistema de gerenciamento de tarefas (Task Manager) com as seguintes funcionalidades:

  • CRUD de usuários (cadastro, listagem, atualização, exclusão)
  • CRUD de tarefas (criação, atribuição, conclusão, deleção)
  • Autenticação via JWT (login, refresh token, middleware de proteção)
  • Banco de dados relacional com SQLite (via Prisma ORM)
  • Testes unitários e de integração
  • Documentação automática dos endpoints

A escolha do backend agentes IA não é acidental. Cada etapa foi desenhada para explorar os pontos fortes de diferentes agentes: Claude Code para tarefas que exigem compreensão de contexto (refatoração, estruturação), e Codex para geração de código padronizado e repetitivo (models, validações).

Imagem sugerida: Diagrama de arquitetura do sistema mostrando cliente -> API Express -> Prisma -> SQLite, com agentes de IA atuando em cada camada.

Setup do projeto: estrutura inicial com agentes de IA

Antes de escrever uma linha de código manualmente, vamos usar agentes de IA para criar a estrutura base do projeto.

Inicialização com Claude Code

Abra o terminal na pasta do projeto e execute:

mkdir task-manager-api cd task-manager-api npm init -y

Agora, use Claude Code para configurar as dependências e a estrutura de diretórios:

claude "Crie um projeto Node.js com Express e Prisma para uma API REST de gerenciamento de tarefas. Instale as dependências: express, cors, helmet, morgan, prisma, @prisma/client, jsonwebtoken, bcryptjs, express-validator. Crie a estrutura de pastas: src/routes, src/controllers, src/models, src/middleware, src/utils, tests/. Configure o Prisma com SQLite."

Claude Code executa os comandos npm, cria os diretórios e configura o schema Prisma inicial. Em segundos, você tem a espinha dorsal do projeto pronta.

Configuração do TypeScript (opcional, mas recomendado)

Para um projeto mais robusto, peça ao Claude Code para adicionar TypeScript:

claude "Adicione TypeScript ao projeto. Instale typescript, ts-node, @types/express, @types/jsonwebtoken, @types/bcryptjs. Crie um tsconfig.json com strict mode habilitado e configure scripts no package.json para dev (ts-node-dev --respawn) e build (tsc)."

Imagem sugerida: Captura de tela do terminal mostrando Claude Code criando a estrutura de diretórios automaticamente.

Estrutura resultante

Após o setup, sua estrutura de projeto deve se parecer com:

task-manager-api/ ├── src/ │ ├── routes/ │ ├── controllers/ │ ├── models/ │ ├── middleware/ │ └── utils/ ├── prisma/ │ └── schema.prisma ├── tests/ ├── package.json └── tsconfig.json

A criação de API REST com Claude Code nessa etapa inicial poupa cerca de 30 minutos de configuração manual — instalação de pacotes, criação de pastas, arquivos de configuração. O agente também já valida se as versões das dependências são compatíveis.

Rotas e controllers com Claude Code

Com a estrutura pronta, o próximo passo é definir as rotas e controllers da API. Esta é a etapa onde Claude Code brilha, pois ele entende o contexto do projeto e pode criar código que respeita a arquitetura já estabelecida.

Definição das rotas de usuário

Peça ao Claude Code para criar as rotas de CRUD de usuários, passando o contexto do projeto:

claude "No diretório src/routes, crie o arquivo userRoutes.ts com as seguintes rotas RESTful para o controller UserController: - POST /users — criar usuário - GET /users — listar todos (rota protegida) - GET /users/:id — buscar por ID (rota protegida) - PUT /users/:id — atualizar (rota protegida) - DELETE /users/:id — deletar (rota protegida) Use express.Router() e importe o controller de src/controllers/UserController.ts. O middleware de autenticação está em src/middleware/auth.ts."

Claude Code analisa a estrutura existente, verifica se o controller e middleware referenciados existem, e cria o arquivo com as importações corretas.

Criação dos controllers

Agora, peça a implementação do controller de usuários:

claude "Crie o arquivo src/controllers/UserController.ts com métodos para cada rota de usuário. Cada método deve: 1. Extrair parâmetros da requisição (body, params, query) 2. Validar campos obrigatórios com express-validator 3. Chamar o Prisma service para operações no banco 4. Retornar respostas padronizadas no formato { success: boolean, data?: any, error?: string } 5. Tratar erros com try/catch e retornar status HTTP apropriados Use o padrão async/await. O Prisma client está em src/models/prisma.ts."

Controllers de tarefas

Repita o processo para tarefas:

claude "Crie src/controllers/TaskController.ts com CRUD de tarefas. Uma tarefa tem: id (UUID), title (obrigatório), description (opcional), status (enum: pending, in_progress, completed), priority (enum: low, medium, high), assignedTo (relacionamento com User), createdAt, updatedAt. Inclua validações e tratamento de erros."

Conexão central das rotas

claude "Crie src/routes/index.ts que agrupa todas as rotas da aplicação: userRoutes em /users e taskRoutes em /tasks. Exporte um único router para usar no app.ts."

O agente cria a integração correta entre os arquivos, garantindo que as importações estejam consistentes.

Imagem sugerida: Trecho de código do VS Code mostrando uma rota e seu controller lado a lado, com realce nos trechos gerados por IA.

O que Claude Code faz de diferente

Diferente de um gerador de código simples, Claude Code:

  • Entende a estrutura existente: antes de criar um arquivo, ele lê os arquivos vizinhos para garantir compatibilidade de imports e tipos
  • Valida consistência: se você pede um controller que referencia prisma.ts, ele verifica se o arquivo existe e usa a mesma instância do Prisma Client
  • Aplica padrões do projeto: se o arquivo utils/response.ts define um formato de resposta, Claude Code usa esse formato automaticamente em todos os controllers

Isso faz com que a API Node.js Express agente resultante tenha coesão arquitetural — como se um único desenvolvedor sênior tivesse escrito tudo.

Modelos e banco com Codex

Enquanto Claude Code é excelente para estruturação de rotas e controllers, Codex (da OpenAI) se destaca na geração de código repetitivo e padronizado — como models, migrações e schemas de banco.

Schema Prisma com Codex

Vamos usar Codex para gerar o schema completo do banco de dados:

opencode "Gere o schema Prisma completo para SQLite com os seguintes modelos: Model User: - id: String (UUID, default) - name: String - email: String (unique) - password: String (hash) - role: enum (USER, ADMIN), default USER - createdAt: DateTime - updatedAt: DateTime - tasks: relation Task[] Model Task: - id: String (UUID, default) - title: String - description: String? - status: enum (PENDING, IN_PROGRESS, COMPLETED), default PENDING - priority: enum (LOW, MEDIUM, HIGH, CRITICAL), default MEDIUM - userId: String - user: relation User @relation(fields: [userId], references: [id]) - createdAt: DateTime - updatedAt: DateTime Use @map para snake_case no banco e @@map para nomes de tabela em português se desejar."

Codex gera o schema completo com todos os enums, relações e anotações. O resultado é mais rápido do que escrever manualmente, e a syntaxe vem correta de primeira — sem erros de digitação ou esquecimento de campos obrigatórios.

Geração de migrações

Com o schema gerado, peça ao Codex para criar o script de migração:

opencode "Crie um script npm chamado 'db:migrate' que executa 'npx prisma migrate dev --name init' e outro chamado 'db:seed' que executa um arquivo prisma/seed.ts. Gere também o arquivo prisma/seed.ts com dados iniciais: 2 usuários admin e 5 tarefas de exemplo."

Validações Zod com Codex

Para garantir a integridade dos dados de entrada, use Codex para gerar schemas de validação com Zod:

opencode "Crie schemas de validação Zod para User e Task em src/utils/validation.ts: - createUserSchema: name (string 3-100), email (email válido), password (string 8+ com 1 número e 1 caractere especial), role (opcional, enum USER|ADMIN) - updateUserSchema: todos campos opcionais - createTaskSchema: title (string 3-200), description (opcional, string), priority (opcional, enum) - updateTaskSchema: todos campos opcionais, status incluso"

A API REST Codex nessa etapa mostra seu valor: gerar schemas de validação, models e migrações é um trabalho de alto volume e baixa complexidade — exatamente o tipo de tarefa onde um agente de IA supera a digitação manual em velocidade e consistência.

Imagem sugerida: Side-by-side do schema Prisma gerado por Codex (lado esquerdo) e a tabela SQLite resultante (lado direito), mostrando a correspondência exata.

Por que usar dois agentes diferentes?

A divisão de trabalho entre Claude Code e Codex não é arbitrária:

TarefaAgenteMotivo
Estrutura de diretórios, rotas, controllersClaude CodeEntende contexto do projeto, evita conflitos de import
Schema Prisma, validações Zod, migraçõesCodexGeração rápida de código padronizado e repetitivo
Refatoração e ajustes finosClaude CodeCompreensão profunda da arquitetura

Essa orquestração entre agentes é exatamente o que chamamos de backend agentes IA: não usar um único agente para tudo, mas sim cada agente onde ele entrega mais valor.

Autenticação JWT com agentes de IA

Autenticação é uma das partes mais críticas de uma API REST. Erros de implementação podem expor dados sensíveis. Vamos usar agentes de IA para gerar uma implementação robusta — e depois revisar cada linha.

Middleware de autenticação com Claude Code

claude "Crie src/middleware/auth.ts com: 1. Função generateToken(userId: string): string — gera JWT com payload { userId }, expiração 24h, secret da env JWT_SECRET 2. Função verifyToken(token: string): string | null — verifica token e retorna userId ou null 3. Middleware authenticate — extrai token do header Authorization (Bearer), verifica, e anexa userId ao request. Retorna 401 se token inválido ou ausente. 4. Middleware requireAdmin — verifica se o usuário logado tem role ADMIN no banco. Retorna 403 se não for. Use tipos estendidos do Express (declare module 'express' para adicionar userId ao Request)."

Implementação do login

claude "Adicione ao UserController os métodos: - login(req, res): recebe email e password, busca usuário no banco, compara hash com bcryptjs, gera token JWT, retorna { token, user } ou 401 - refreshToken(req, res): recebe token válido, gera novo token com expiração renovada, retorna novo token ou 401 Atualize as rotas em userRoutes.ts para incluir POST /login e POST /refresh (ambas públicas, sem middleware)."

Proteção das rotas

Com o middleware criado, Claude Code pode atualizar automaticamente todas as rotas que devem ser protegidas:

claude "Atualize src/routes/userRoutes.ts e src/routes/taskRoutes.ts: aplique o middleware authenticate em todas as rotas, exceto POST /users (cadastro público) e POST /login. Aplique requireAdmin nas rotas DELETE."

O agente modifica apenas os imports e a aplicação dos middlewares, preservando o resto do código.

Considerações de segurança

Embora a geração com IA acelere o processo, é essencial revisar:

  • A env JWT_SECRET é carregada corretamente (dica: use dotenv e nunca comite o arquivo .env)
  • O hash de senha usa bcryptjs com salt rounds >= 10
  • O token JWT tem expiração razoável (24h para access, 7d para refresh)
  • O middleware authenticate lida com edge cases (token expirado, mal formatado, header ausente)

Imagem sugerida: Fluxograma do processo de autenticação: requisição -> middleware -> verificação JWT -> controller -> resposta.

Testes automatizados gerados por IA

Uma API REST sem testes é uma bomba-relógio. Agentes de IA podem gerar a suíte de testes inteira, cobrindo rotas, controllers, middleware e utils.

Configuração do ambiente de testes

claude "Configure o projeto para testes com Jest e Supertest. Instale jest, ts-jest, @types/jest, supertest, @types/supertest. Crie jest.config.ts com preset ts-jest, testEnvironment node, e roots apontando para tests/. Adicione script 'test' no package.json."

Testes de integração para rotas de usuário

claude "Crie tests/integration/userRoutes.test.ts com testes para cada rota de usuário: 1. POST /users — deve criar usuário com dados válidos (status 201), rejeitar email duplicado (409), rejeitar senha fraca (400) 2. POST /login — deve retornar token com credenciais válidas (200), rejeitar senha errada (401) 3. GET /users — deve retornar lista (200), rejeitar sem token (401) 4. GET /users/:id — deve retornar usuário específico (200), retornar 404 se não existir 5. PUT /users/:id — deve atualizar dados (200), rejeitar email duplicado (409) 6. DELETE /users/:id — deve deletar (200), rejeitar sem role admin (403) Use beforeAll para criar um banco de testes in-memory e afterAll para limpar."

Testes para rotas de tarefas

claude "Crie tests/integration/taskRoutes.test.ts: 1. POST /tasks — criar tarefa (201), rejeitar sem título (400) 2. GET /tasks — listar tarefas do usuário logado (200), filtrar por status (200) 3. GET /tasks/:id — buscar tarefa (200), retornar 404 se não existir 4. PUT /tasks/:id — atualizar status para completed (200) 5. DELETE /tasks/:id — deletar tarefa (200), rejeitar tarefa de outro usuário (403)"

Testes unitários para middleware

claude "Crie tests/unit/auth.test.ts para testar o middleware de autenticação isoladamente: 1. generateToken — deve criar token válido com userId correto 2. verifyToken — deve decodificar token válido, retornar null para token inválido, retornar null para token expirado 3. authenticate — deve chamar next() com token válido, retornar 401 sem header, retornar 401 com token inválido Use mocks para o Prisma Client."

Após a geração, execute os testes:

npm test

Claude Code pode até corrigir falhas automaticamente se você pedir:

claude "Analise a saída dos testes, identifique as falhas e corrija os arquivos de implementação para que todos os testes passem."

Isso cria um ciclo virtuoso: IA gera testes -> IA executa -> IA corrige implementação -> testes passam.

Imagem sugerida: Captura de tela do terminal mostrando todos os testes passando (green checkmarks) com o relatório de cobertura.

Pipeline completo: integrando tudo

Com cada parte funcionando isoladamente, o último passo é integrar tudo em um pipeline coeso. Vamos usar Claude Code para conectar todas as peças.

Arquivo principal da aplicação

claude "Crie src/app.ts que configura e exporta o Express app: 1. Middlewares globais: cors, helmet, morgan, express.json() 2. Rotas importadas de src/routes/index.ts montadas em /api 3. Middleware de erro global (trata erros não capturados, retorna 500 com mensagem amigável) 4. Rota GET /health para health check Crie src/server.ts que importa app.ts, escuta na porta da env PORT (default 3000), e loga o start."

Scripts do package.json

claude "Atualize o package.json com scripts completos: - dev: ts-node-dev --respawn src/server.ts - build: tsc - start: node dist/server.js - test: jest --verbose - test:coverage: jest --coverage - db:migrate: npx prisma migrate dev - db:seed: npx ts-node prisma/seed.ts - db:reset: npx prisma migrate reset --force

Variáveis de ambiente

claude "Crie .env.example com todas as variáveis de ambiente do projeto: PORT, DATABASE_URL, JWT_SECRET, JWT_EXPIRES_IN, NODE_ENV. Crie também um .env com valores padrão para desenvolvimento. Adicione .env ao .gitignore."

Docker (opcional)

Para ambientes de produção, peça ao Claude Code para gerar Dockerfile e docker-compose:

claude "Crie Dockerfile multi-stage para o projeto: stage 1 com node:20-alpine para build (npm ci, npm run build), stage 2 com node:20-alpine apenas com dist/ e node_modules. Crie docker-compose.yml com serviço da API na porta 3000 e volume para o banco SQLite."

Validação final

Execute o pipeline completo para verificar se tudo funciona:

# 1. Instalar dependências npm ci # 2. Migrar banco npm run db:migrate # 3. Popular dados iniciais npm run db:seed # 4. Rodar testes npm test # 5. Build npm run build # 6. Iniciar servidor (modo produção) npm start

Se algum passo falhar, peça ao Claude Code para diagnosticar e corrigir:

claude "O passo X falhou com o erro Y. Analise a causa raiz e corrija."

O resultado final é uma API Node.js Express agente completa, testada e pronta para deploy — construída em uma fração do tempo que levaria manualmente.

Imagem sugerida: Pipeline visual mostrando as 6 etapas (install -> migrate -> seed -> test -> build -> start) com indicadores verde/vermelho para cada uma.

FAQ — Perguntas Frequentes

Qual a diferença entre Claude Code e Codex para criar APIs REST?

Claude Code entende melhor o contexto do projeto e é ideal para estruturar rotas, controllers e refatorações. Codex é mais rápido para gerar código padronizado como models, schemas de validação e testes. A melhor estratégia é usar os dois em orquestração, cada um na tarefa onde entrega mais valor.

Preciso saber programar para criar APIs REST com agentes de IA?

Sim, é essencial ter conhecimento de programação. Agentes de IA aceleram o desenvolvimento, mas você precisa entender o código gerado para revisar a segurança, corrigir bugs e adaptar à sua arquitetura. O agente é um assistente, não um substituto.

Agentes de IA geram código seguro para APIs REST?

O código gerado segue boas práticas comuns (hash de senhas, JWT com expiração, validação de entrada), mas não substitui uma revisão de segurança humana. Sempre revise middlewares de autenticação, sanitização de entrada e tratamento de erros antes de ir para produção.

Posso usar essa abordagem com qualquer banco de dados?

Sim. O tutorial usa SQLite via Prisma para simplificar, mas você pode adaptar para PostgreSQL, MySQL ou MongoDB. Basta alterar o datasource no schema.prisma e atualizar a DATABASE_URL. O Prisma abstrai a maior parte das diferenças entre bancos relacionais.

Quanto tempo economiza usar agentes para desenvolver uma API REST?

Em projetos de porte médio (15-20 endpoints), agentes de IA podem reduzir o tempo de desenvolvimento de 3-4 dias para 6-8 horas — uma economia de 60% a 75%. A maior economia está na geração de código repetitivo (models, validações, testes) e na correção de bugs.

É possível usar Claude Code e Codex simultaneamente no mesmo projeto?

Sim. Com o Orquestra, você conecta Claude Code e Codex no mesmo canvas, define papéis para cada agente e sincroniza o diretório do projeto. Um agente pode criar controllers enquanto o outro gera testes — tudo em paralelo, sem conflito de edição.

Comece a desenvolver APIs com agentes hoje

Neste tutorial, você viu na prática como APIs REST agentes IA podem transformar o desenvolvimento de backend. Usamos Claude Code para estruturação de rotas, controllers e middlewares; Codex para models, schemas e validações; e a combinação dos dois para gerar uma suíte completa de testes. O resultado é uma API REST funcional, testada e pronta para produção — desenvolvida em horas, não dias.

O segredo não está em usar um único agente para tudo, mas em orquestrar múltiplos agentes onde cada um entrega mais valor. Claude Code para contexto e arquitetura, Codex para volume e repetição — juntos, eles cobrem o espectro completo do desenvolvimento de backend agentes IA.

Quer levar essa orquestração para o próximo nível? O Orquestra foi construído exatamente para isso: conectar Claude Code, Codex e outros agentes no mesmo canvas infinito, definir papéis, sincronizar diretórios e coordenar tarefas em paralelo — tudo no Windows 11, sem configuração complexa.

Baixe o Orquestra para Windows 11 e comece seu teste grátis de 7 dias — sem necessidade de cartão de crédito.

Links internos recomendados

Links externos recomendados

  • Express.js Documentation — documentação oficial do framework web utilizado no tutorial
  • Prisma ORM Documentation — guia completo do Prisma, usado para modelagem e acesso a banco de dados
  • JWT.io — ferramenta para decodificar e depurar tokens JWT durante o desenvolvimento

Imagens/GIFs sugeridos para o post

  1. Diagrama de arquitetura: Cliente -> API Express -> Prisma -> SQLite com agentes atuando em cada camada
  2. Setup do projeto: Captura de tela do terminal mostrando Claude Code criando a estrutura de diretórios
  3. Código VS Code: Split view com rota e controller lado a lado, destaques nos trechos gerados por IA
  4. Schema Prisma vs Tabela SQLite: Comparação visual lado a lado mostrando correspondência exata
  5. Fluxo de autenticação: Fluxograma requisição -> middleware -> JWT -> controller -> resposta
  6. Testes passando: Captura do terminal com todos os testes verdes e relatório de cobertura
  7. Pipeline completo: Diagrama das 6 etapas (install -> migrate -> seed -> test -> build -> start)

Posts relacionados

Automação

Automação de Tarefas com Agentes de IA

Guia prático sobre refatoração, testes e documentação com Claude Code e Codex.

Guia técnico

Performance de Agentes de IA no Windows 11

Otimize sua máquina para rodar múltiplos agentes simultaneamente.

Claude Code

Claude Code vs OpenCode

Comparativo técnico entre as principais ferramentas de agente IA para Windows.

Pronto para orquestrar seus agentes?

Baixe o Orquestra para Windows 11 e comece a coordenar seus agentes de IA em um canvas infinito. Grátis por 7 dias.

Começar teste grátis