Cómo crear un backend de API REST con Claude Code: guía paso a paso (2026)

por Jasmine, una dev que publica backends con Claude Code todos los días.

¿Por qué usar Claude Code para crear un backend de API REST?

Claude Code es una CLI agéntica: lee todo tu repositorio, genera varios archivos a la vez y luego ejecuta comandos y pruebas para revisar su propio trabajo (según la documentación oficial de Anthropic, actualizada en 2026). Es justo ese rasgo lo que hace que encaje mejor en el trabajo de backend que un chatbot de pegar-y-copiar. Una API REST es, en el fondo, un montón de código repetitivo - models, migraciones, controladores CRUD, validación, pruebas, docs. Es un trabajo lento y de baja creatividad, y ahí es donde la IA más te acelera.

La mayor ventaja es la velocidad de scaffolding. En lugar de teclear a mano seis endpoints casi idénticos, describes el recurso una sola vez y Claude Code genera tanto la capa de datos como la capa REST, y además la ejecuta. También es bueno en las partes "tediosas", como escribir un esquema Zod o Pydantic que coincida con tu model, o levantar una suite de pruebas para cada ruta.

Pero aquí está la parte que tienes que quedarte para ti: sigues siendo quien revisa. Claude Code no entiende tu contexto de seguridad - tiende a entregar valores por defecto flojos (falta de authz en una ruta, secretos en el código, validación de adorno). Para cualquier cosa que toque dinero o permisos, lo que produce la IA es solo un borrador sólido. Si la herramienta es nueva para ti, lee primero qué es Claude Code para ver cómo funciona antes de encargarle trabajo de backend.

Qué preparar antes de empezar

Un checklist para repasar antes de abrir Claude Code - deja esto listo para que toda la sesión fluya:

• Claude Code instalado y funcionando en tu terminal - mira la guía de instalación de Claude Code si aún no lo configuraste.
• Runtime: Node 20+ (para Express) o Python 3.11+ (para FastAPI).
• Base de datos: PostgreSQL (nivel producción) o SQLite (dev rápido, sin servidor).
• Un repositorio Git ya iniciado con git init - así revisas cada diff y reviertes cuando haga falta.
• Un archivo CLAUDE.md que deje claras las convenciones del proyecto - esa es la mayor diferencia entre una salida limpia y un desastre.

Coloca el CLAUDE.md en la raíz del repositorio y Claude Code lo lee automáticamente en cada sesión. Para un backend, declara de entrada tus convenciones de capas, la validación y el formato de error, para no repetirte:

# CLAUDE.md - backend conventions

## Architecture
- Three layers: routes -> controllers -> services. No DB queries in controllers.
- ORM: Prisma. All queries go through a service; no raw SQL unless required.

## Validation & errors
- Validate input with Zod at the top of every handler.
- Errors return JSON: { "error": { "code": string, "message": string } }
- Status codes: 200/201 success, 400 validation, 401 unauthenticated,
 403 forbidden, 404 not found, 500 server error.

## Security (REQUIRED, do not skip)
- NEVER hardcode secrets. Read them from process.env.
- Every write/update/delete route must pass through auth middleware.
- Never return sensitive fields (passwordHash) in a response.

## Tests
- Every endpoint has at least 1 happy-path test + 1 error test (Jest + Supertest).

Con ese único archivo, la calidad de lo que Claude Code genera sube de nivel - porque ahora tiene un "contrato" que seguir en vez de adivinar tu estilo.

Elegir una stack - ¿Node/Express o Python/FastAPI?

No hay una única stack "correcta", pero algunas encajan mejor en la forma en que trabaja Claude Code. Una comparación rápida de cuatro opciones populares:

Para toda esta guía voy con Express + Prisma + PostgreSQL: JS primero, muy usado, y Prisma da suficiente seguridad de tipos sin el peso de NestJS. Si tu equipo es de Python, FastAPI + SQLAlchemy también es excelente - los type hints de Pydantic ayudan de verdad a que Claude Code cometa menos errores de tipo. El punto clave: elige una stack y quédate con ella durante todo el build. No dejes que Claude Code "elija por su cuenta" a mitad del proyecto - esa es la receta de una mezcla híbrida que nadie quiere mantener.

Paso 1 - Planifica endpoints y esquema con Claude Code

No le digas a Claude Code "constrúyeme una API" y lo dejes ponerse a programar. Empieza por la planificación: pídele que haga una lluvia de ideas de los recursos, endpoints y el esquema de la BD primero, para aprobar el diseño antes de que exista una sola línea de código. Un prompt para copiar y pegar:

I want to build a REST API for managing "tasks" with Express + Prisma + PostgreSQL.
Before writing code, propose:
1. The endpoint list (method + path + description) for tasks CRUD.
2. The Task table schema (fields, types, constraints).
3. A sample response shape for each endpoint.
Present it as a table. DO NOT code yet - I want to review first.

Claude Code te devuelve una tabla de endpoints así, para que le des el visto bueno:

Revisa con cuidado aquí: ¿los campos están completos, necesitas un enum de status, la paginación es por cursor o por offset? Corregir el diseño con palabras es mucho más barato que corregir código generado. También es aquí donde la mentalidad de planificar antes de programar con Claude Code rinde frutos.

Paso 2 - Genera el andamiaje del proyecto y la capa de datos

Con el diseño cerrado, ahora dejas que Claude Code genere el andamiaje. El prompt:

Scaffold an Express + TypeScript project per the plan we just approved:
- Install express, prisma, @prisma/client, zod, dotenv.
- Create the Prisma schema for the Task model as designed.
- Generate the first migration and a seed file with 3 sample tasks.
- Folder structure: src/routes, src/controllers, src/services, src/lib.
After creating it, STOP so I can read the migration before it runs.

El esquema Prisma resultante debería verse así:

// prisma/schema.prisma
model Task {
 id String @id @default(uuid())
 title String
 detail String?
 status Status @default(TODO)
 createdAt DateTime @default(now())
 updatedAt DateTime @updatedAt
}

enum Status {
 TODO
 DOING
 DONE
}

Lee la migración antes de ejecutarla - esto no es un consejo de trámite. Claude Code a veces añade una columna de más, pone un default equivocado o se salta un índice necesario. Ejecuta npx prisma migrate dev --name init solo cuando entiendas el diff. Si quieres profundizar en esta parte, mira usar Claude Code con tu base de datos.

Paso 3 - Construye los endpoints CRUD un recurso a la vez

La regla de oro: un endpoint a la vez, no "constrúyelos todos de golpe". Cuando le pides cinco rutas de una sola vez a Claude Code, tiende a desviarse y a ti te cuesta revisar. Haz uno, revísalo, haz commit y pasa al siguiente. Empieza por POST y GET:

// src/controllers/task.controller.ts
import { Request, Response } from "express";
import { z } from "zod";
import * as taskService from "../services/task.service";

const createSchema = z.object({
 title: z.string().min(1).max(200),
 detail: z.string().max(2000).optional(),
 status: z.enum(["TODO", "DOING", "DONE"]).optional(),
});

export async function createTask(req: Request, res: Response) {
 const parsed = createSchema.safeParse(req.body);
 if (!parsed.success) {
 return res.status(400).json({
 error: { code: "VALIDATION_ERROR", message: parsed.error.message },
 });
 }
 const task = await taskService.create(parsed.data);
 return res.status(201).json(task);
}

export async function listTasks(req: Request, res: Response) {
 const tasks = await taskService.findAll();
 return res.status(200).json(tasks);
}

Dos cosas que revisar en la revisión: ¿el formato de la respuesta coincide con tu CLAUDE.md (el objeto de error está en la forma correcta) y el código de estado es semánticamente correcto (201 para creación, no 200)? Aquí es donde Claude Code se vuelve descuidado - suele devolver 200 para todo a menos que lo especifiques.

Claude Code usa skills para estandarizar estos patrones, así que si tienes tu propia skill de backend, la salida será mucho más consistente que con un prompt pelado.

Paso 4 - Autenticación y validación (JWT o API key)

La mayoría de los tutoriales se detienen en "añade JWT si hace falta". No basta. Aquí tienes un middleware JWT de verdad que protege las rutas de escritura/actualización/eliminación:

// src/lib/auth.ts
import { Request, Response, NextFunction } from "express";
import jwt from "jsonwebtoken";

export function requireAuth(req: Request, res: Response, next: NextFunction) {
 const header = req.headers.authorization;
 if (!header?.startsWith("Bearer ")) {
 return res.status(401).json({
 error: { code: "UNAUTHORIZED", message: "Missing token" },
 });
 }
 try {
 const payload = jwt.verify(header.slice(7), process.env.JWT_SECRET!);
 (req as any).user = payload;
 next();
 } catch {
 return res.status(401).json({
 error: { code: "INVALID_TOKEN", message: "Invalid token" },
 });
 }
}

Acóplalo a las rutas de escritura: router.post("/tasks", requireAuth, createTask). Para una API interna sencilla, comparar contra una API key constante también alcanza - pero compara siempre con una función de tiempo constante, nunca con un === pelado.

Revisión manual obligatoria: Claude Code tiende a entregar valores por defecto débiles - olvidar acoplar requireAuth en la ruta correcta, dejar que JWT_SECRET caiga en una cadena fija en el código, o saltarse la verificación de propiedad (el usuario A edita la tarea del usuario B). Después de que la IA genere el middleware, repásalo a mano: ¿cada ruta sensible tiene autenticación, el secreto se lee del env y la autorización (no solo la autenticación) es de verdad correcta?

Paso 5 - Prueba la API (uniendo TDD con IA)

Claude Code no solo escribe las pruebas, sino que ejecuta las pruebas y el curl por sí mismo para verificar - esa es la verdadera ventaja agéntica. Prompt: "Escribe pruebas Jest + Supertest para POST /tasks y GET /tasks, cubriendo el camino feliz y un caso de error de validación, y luego ejecútalas." Una prueba de ejemplo:

// tests/task.test.ts
import request from "supertest";
import app from "../src/app";

describe("POST /tasks", () => {
 it("creates a valid task and returns 201", async () => {
 const res = await request(app)
 .post("/tasks")
 .set("Authorization", `Bearer ${process.env.TEST_TOKEN}`)
 .send({ title: "Write post F1" });
 expect(res.status).toBe(201);
 expect(res.body.title).toBe("Write post F1");
 });

 it("returns 400 when title is missing", async () => {
 const res = await request(app)
 .post("/tasks")
 .set("Authorization", `Bearer ${process.env.TEST_TOKEN}`)
 .send({});
 expect(res.status).toBe(400);
 });
});

Verifica a mano con curl para ver la respuesta JSON real:

$ curl -s -X POST http://localhost:3000/tasks \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"title":"Write post F1","status":"DOING"}'

{
 "id": "a3f1c9e2-...-8b71",
 "title": "Write post F1",
 "detail": null,
 "status": "DOING",
 "createdAt": "2026-08-09T04:12:30.882Z",
 "updatedAt": "2026-08-09T04:12:30.882Z"
}

Hacer que Claude Code escriba las pruebas antes de implementar es la forma eficaz de aplicar TDD con IA: las pruebas actúan como el "contrato" y la IA programa hasta que se ponen en verde.

Paso 6 - Seguridad de producción y manejo de errores

Esta es la parte que los competidores dejan casi en blanco. Antes de exponer la API a internet, pídele a Claude Code que añada las siguientes capas - pero revisa el checklist tú misma:

• Rate limiting: express-rate-limit para frenar la fuerza bruta y el abuso (digamos, 100 req/min/IP).
• CORS: pon en la whitelist orígenes específicos; no dejes origin: "*" en una API autenticada.
• Env/secretos: cada clave vía .env, añade .env al .gitignore, entrega una plantilla .env.example.
• Validación de entrada: ya la maneja Zod en cada handler - nunca confíes en los datos del cliente.
• Handler central de errores: un middleware final que atrapa todos los errores y no filtra stack traces en las respuestas de producción.
• Helmet: fija los headers HTTP de seguridad básicos.

Un checklist OWASP cortito para repasar: alguna inyección (Prisma bloquea SQLi con consultas parametrizadas), algún control de acceso roto (revisa la authz en cada ruta), alguna exposición de datos sensibles (no devuelvas campos de más). Si quieres que el propio Claude Code busque agujeros, mira cómo ejecutar una auditoría de seguridad con Claude Code.

Paso 7 - Despliega la API en una URL de verdad

Yo uso Railway en esta demo porque provisiona Postgres de fábrica y despliega desde Git en unos minutos. Los pasos:

1. Haz push del repositorio a GitHub.
2. En Railway, crea un proyecto a partir del repositorio y añade un servicio PostgreSQL - genera automáticamente la DATABASE_URL.
3. Define las variables de entorno de producción: JWT_SECRET, DATABASE_URL, NODE_ENV=production.
4. Define el comando de build npx prisma migrate deploy && npm run build y el comando de start npm start.

Si lo quieres más portátil (que corra también en Render, Fly.io o una VPS), añade un Dockerfile mínimo:

# Dockerfile
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npx prisma generate && npm run build
EXPOSE 3000
CMD ["npm", "start"]

Después de desplegar, entra al endpoint por la URL en vivo para confirmar que la migración corrió y que el entorno está correcto. El detalle plataforma por plataforma está en la guía sobre desplegar apps con Claude Code.

Ir más rápido: AgentKit trae la skill ak-backend-development

Una línea para evitar confusiones: AgentKit aquí es un paquete de kit para Claude Code (agentkit.best, la CLI ak) - no el AgentKit de OpenAI (Agent Builder/ChatKit, lanzado el 06/10/2025). Mismo nombre, cosas completamente distintas.

Los 7 pasos de arriba te piden declarar convenciones en el CLAUDE.md y volver a enunciar los patrones en cada sesión. AgentKit para Claude Code (20% de descuento por el enlace) empaqueta la skill ak-backend-development que, según su descripción, admite Node/Python/Go (NestJS, FastAPI, Django), autenticación OAuth/JWT, un checklist de seguridad OWASP y Docker/K8s. En otras palabras, Claude Code ejecuta esos mismos 7 pasos contra convenciones estándar ya hechas, así que no reconstruyes el "contrato" desde cero en cada proyecto.

Opinión honesta: el kit no es obligatorio - puedes hacer todo esto a mano, y este artículo acaba de demostrarlo. El kit solo ahorra esfuerzo de configuración si creas backends a menudo. El Engineer Kit cuesta $99 (el sitio no menciona una cuota recurrente), con "garantía de devolución del dinero" y "actualizaciones de por vida". Mira qué hay dentro del Engineer Kit de AgentKit para sopesarlo antes de comprar.

Límites reales y cuándo debes revisar a mano

Esta es la sección que ningún competidor tiene, y es la más importante. Tras muchos proyectos de backend con Claude Code, estos son los modos de fallo que no dejo de tener que atrapar:

• Imports/llamadas de ORM equivocadas: llamar a un método Prisma que no existe, o importar la versión equivocada del paquete - el código parece correcto pero falla en runtime.
• Falta de authz en una ruta: tiene authn (quién eres) pero se salta la authz (si puedes) - un usuario edita los datos de otro.
• Validación floja: valida el título pero olvida el límite de longitud, olvida sanear, deja pasar tipos de dato raros.
• Consultas N+1: un bucle golpeando la BD por cada ítem en vez de una sola query - va bien en dev, se cae en producción.
• Secretos fijos en el código: un JWT_SECRET o cadena de conexión metido directo en el código como fallback.
• "Parece que corre" pero la lógica de negocio está mal: compila, la prueba del camino feliz está en verde, pero el cálculo o la lógica de estado está mal - solo quien conoce el dominio lo va a notar.

Mi regla: Claude Code para el boilerplate, humanos para revisar autenticación, seguridad y lógica de dinero. La IA genera el 80% del volumen muchas veces más rápido; el 20% restante - justo la parte de alto riesgo - es donde no puedes soltar las manos. Eso no es una debilidad de la herramienta, es cómo usarla correctamente.

Preguntas frecuentes (FAQ)

¿Claude Code está listo para producción en backends?

No de forma totalmente automatizada. Claude Code genera código real, funcional y bien estructurado, pero la autenticación, los permisos, la seguridad y la lógica de negocio necesitan una revisión humana cuidadosa antes de producción. Trata la salida como un borrador de alta calidad, no como una versión final.

¿Necesito saber programar o un principiante puede hacerlo?

Necesitas poder leer código y entender HTTP/REST y bases de datos a nivel básico para revisar la salida. Un principiante igual consigue una API funcionando, pero le costará detectar los bugs de seguridad o de lógica que Claude Code introduce - así que aprende a la par, no lo delegues a ciegas.

¿Puede construir GraphQL o gRPC?

Sí. Esta guía demuestra REST por ser el más común, pero Claude Code también construye GraphQL (Apollo) y gRPC. Los principios son idénticos: planifica el esquema primero, construye por partes y revisa tú misma la autenticación/seguridad.

¿Qué stack encaja mejor con Claude Code?

Express + Prisma (JS) y FastAPI + SQLAlchemy (Python) son los dos mejores encajes - muchos patrones familiares y suficiente seguridad de tipos para reducir alucinaciones. FastAPI lleva ventaja porque sus type hints recortan los errores de tipo.

¿El código que genera Claude Code es seguro?

No por defecto. Claude Code tiende a entregar valores por defecto flojos: falta de authz, secretos en el código, validación endeble. Tienes que ejecutar el checklist de seguridad por tu cuenta (rate limiting, CORS, env, OWASP) y revisar cada ruta sensible antes de desplegar.

¿Cuánto tarda una API CRUD básica?

Alrededor de 30 a 60 minutos para una API REST CRUD completa con autenticación básica y pruebas, incluido el tiempo de revisión. El scaffolding y el boilerplate son rápidos; el tiempo de verdad se va en revisar autenticación, seguridad y afinar la lógica de negocio.

Conclusión y próximos pasos

Para recapitular los 7 pasos: planificar endpoints y esquema -> generar el andamiaje del proyecto y la capa de datos -> construir el CRUD un recurso a la vez -> añadir autenticación/validación -> probar -> reforzar para producción -> desplegar. Claude Code se encarga del boilerplate; tú te quedas con la revisión de autenticación y lógica - esa es la división del trabajo correcta. Buenas lecturas siguientes: escribir pruebas y TDD con IA para que tu API sea más robusta, y desplegar apps con Claude Code para ponerla en una URL de verdad.