Crear una REST API con Claude Code | Guía práctica para principiantes

“No sé por dónde empezar con las REST APIs” — yo también me sentía así al principio.

Leer documentación se sentía demasiado abstracto. No entendía qué tenía que construir exactamente. Ahí fue cuando empecé a usar Claude Code y me di cuenta de que “construir algo que funcione primero y aprender mientras” es el enfoque más rápido.

En esta guía vamos desde cero conocimiento de REST APIs hasta una API completamente funcional — paso a paso, junto a Claude Code. Todo el código que vas a ver está listo para copiar y pegar.

---

¿Qué es una REST API? (En 3 líneas)

Una REST API es una convención para manipular recursos (datos) en la web mediante HTTP.

Navegador/App  →  Solicitud HTTP  →  Servidor (API)
               ←  Respuesta JSON  ←

Para una API de gestión de usuarios, se ve así:

Objetivo	Método HTTP	URL
Obtener todos los usuarios	GET	/users
Obtener un usuario específico	GET	/users/123
Crear un usuario	POST	/users
Actualizar un usuario	PUT	/users/123
Eliminar un usuario	DELETE	/users/123

Con esto entendido, ya podés empezar a construir con Claude Code.

---

Configuración del entorno

Vamos a usar Hono — un framework web TypeScript liviano. Es más type-safe que Express y funciona de maravilla con Claude Code.

mkdir my-first-api
cd my-first-api
npm init -y
npm install hono
npm install -D typescript @types/node ts-node
npx tsc --init

Creá src/index.ts y preguntale a Claude Code:

claude -p "
Creá un boilerplate de REST API usando Hono en src/index.ts.
- Iniciá el servidor en el puerto 3000
- Agregá un endpoint GET /health para health checks
- Devolvé respuestas en JSON
Comando de ejecución: npx ts-node src/index.ts
"

Claude Code va a generar algo así:

// src/index.ts
import { Hono } from "hono";
import { serve } from "@hono/node-server";

const app = new Hono();

app.get("/health", (c) => {
  return c.json({ status: "ok", timestamp: new Date().toISOString() });
});

serve({ fetch: app.fetch, port: 3000 }, () => {
  console.log("Server running at http://localhost:3000");
});

npx ts-node src/index.ts
# → Server running at http://localhost:3000

curl http://localhost:3000/health
# → {"status":"ok","timestamp":"2026-04-27T07:30:00.000Z"}

¿Funcionó? Ese es tu punto de partida para las REST APIs.

---

Step 1: Crear CRUD básico

Ahora vamos a construir una API para gestionar una lista de Todos. Pedíselo a Claude Code:

claude -p "
Agregá endpoints CRUD de Todo a src/index.ts.
- GET  /todos         — Listar todos los todos
- GET  /todos/:id     — Obtener uno
- POST /todos         — Crear (title: string requerido)
- PUT  /todos/:id     — Actualizar (title: string)
- DELETE /todos/:id   — Eliminar

Manejá los datos en un array en memoria.
Tipo Todo: { id: string, title: string, done: boolean, createdAt: string }
Generá el id con crypto.randomUUID()
"

Código generado:

import { Hono } from "hono";
import { serve } from "@hono/node-server";

const app = new Hono();

// Almacén de datos en memoria
type Todo = { id: string; title: string; done: boolean; createdAt: string };
let todos: Todo[] = [];

// Listar todos
app.get("/todos", (c) => c.json(todos));

// Obtener uno
app.get("/todos/:id", (c) => {
  const todo = todos.find((t) => t.id === c.req.param("id"));
  if (!todo) return c.json({ error: "Not found" }, 404);
  return c.json(todo);
});

// Crear
app.post("/todos", async (c) => {
  const body = await c.req.json();
  if (!body.title) return c.json({ error: "title is required" }, 400);
  const todo: Todo = {
    id: crypto.randomUUID(),
    title: body.title,
    done: false,
    createdAt: new Date().toISOString(),
  };
  todos.push(todo);
  return c.json(todo, 201);
});

// Actualizar
app.put("/todos/:id", async (c) => {
  const idx = todos.findIndex((t) => t.id === c.req.param("id"));
  if (idx === -1) return c.json({ error: "Not found" }, 404);
  const body = await c.req.json();
  todos[idx] = { ...todos[idx], ...body };
  return c.json(todos[idx]);
});

// Eliminar
app.delete("/todos/:id", (c) => {
  const idx = todos.findIndex((t) => t.id === c.req.param("id"));
  if (idx === -1) return c.json({ error: "Not found" }, 404);
  todos.splice(idx, 1);
  return c.json({ message: "Deleted" });
});

serve({ fetch: app.fetch, port: 3000 }, () => {
  console.log("Server running at http://localhost:3000");
});

Probalo:

# Crear un Todo
curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{"title": "Probar Claude Code"}'

# Listar todos
curl http://localhost:3000/todos

# Eliminar (usá el id que te devolvió arriba)
curl -X DELETE http://localhost:3000/todos/<id>

---

Step 2: Agregar validación

“Se puede crear con un título vacío” o “Cualquier string sirve como ID” — la validación previene estos problemas. Preguntale a Claude Code:

claude -p "
Agregá validación con zod para POST /todos y PUT /todos/:id.
- title: string, 1-100 caracteres
- done: (solo PUT) boolean
Devolvé error 400 con mensaje de error específico cuando falle la validación
"

npm install zod

Claude Code agrega schemas de zod:

import { z } from "zod";

const CreateTodoSchema = z.object({
  title: z.string().min(1, "El título debe tener al menos 1 carácter").max(100, "El título no puede superar los 100 caracteres"),
});

const UpdateTodoSchema = z.object({
  title: z.string().min(1).max(100).optional(),
  done: z.boolean().optional(),
});

// POST /todos (con validación)
app.post("/todos", async (c) => {
  const body = await c.req.json().catch(() => ({}));
  const result = CreateTodoSchema.safeParse(body);
  if (!result.success) {
    return c.json({ error: result.error.flatten().fieldErrors }, 400);
  }
  const todo: Todo = {
    id: crypto.randomUUID(),
    title: result.data.title,
    done: false,
    createdAt: new Date().toISOString(),
  };
  todos.push(todo);
  return c.json(todo, 201);
});

Verificá los errores de validación:

# Crear sin título → debería dar error
curl -X POST http://localhost:3000/todos \
  -H "Content-Type: application/json" \
  -d '{}'
# → {"error":{"title":["El título debe tener al menos 1 carácter"]}}

---

Step 3: Unificar el manejo de errores

Por ahora, cada endpoint devuelve errores en formatos distintos. Dejá que Claude Code los estandarice:

claude -p "
Unificá el manejo de errores.
- Formato de respuesta de error común: { error: { code: string, message: string } }
- 404: NOT_FOUND
- 400: VALIDATION_ERROR
- 500: INTERNAL_SERVER_ERROR
Implementá un manejador de errores global usando el onError de Hono
"

// Definición del tipo de error
class AppError extends Error {
  constructor(
    public code: string,
    public message: string,
    public statusCode: number = 400
  ) {
    super(message);
  }
}

// Manejador de errores global
app.onError((err, c) => {
  if (err instanceof AppError) {
    return c.json(
      { error: { code: err.code, message: err.message } },
      err.statusCode as any
    );
  }
  console.error(err);
  return c.json(
    { error: { code: "INTERNAL_SERVER_ERROR", message: "Ocurrió un error inesperado" } },
    500
  );
});

// Uso
app.get("/todos/:id", (c) => {
  const todo = todos.find((t) => t.id === c.req.param("id"));
  if (!todo) throw new AppError("NOT_FOUND", "Todo no encontrado", 404);
  return c.json(todo);
});

---

Step 4: Generar automáticamente la documentación con Swagger UI

Una vez que construiste la API, necesitás documentación. Claude Code lo configura en minutos:

claude -p "
Usá @hono/swagger-ui y @hono/zod-openapi para
agregar Swagger UI en /docs.
Agregá schemas OpenAPI a los endpoints existentes.
"

npm install @hono/swagger-ui @hono/zod-openapi

Una vez listo, entrá a http://localhost:3000/docs para ver la documentación de tu API.

---

El flujo de desarrollo de APIs con Claude Code (resumen)

Este es el flujo que uso día a día:

1. Decirle a Claude Code "Necesito una API que haga X"
    ↓
2. Revisar y probar el código generado
    ↓
3. Iterar: "Corregí esto", "Agregá validación", etc.
    ↓
4. git commit cuando los tests pasen

Mi primer tropiezo (experiencia real)

Cuando construí mi primera API, me salteé el manejo de errores completamente y tuve que agregarlo todo después — lo que me llevó una eternidad. Ahora simplemente agrego “incluí manejo de errores” en mi prompt desde el principio, y el código sale sólido de entrada. El truco con Claude Code es darle todos los requisitos desde el comienzo.

---

3 errores comunes

Error 1: Ignorar los errores de parseo de JSON

// ❌ Los errores aquí pasan desapercibidos
const body = await c.req.json();

// ✅ Capturar los fallos de parseo
const body = await c.req.json().catch(() => null);
if (!body) return c.json({ error: "Invalid JSON" }, 400);

Error 2: Confundir 404 y 400

400: La solicitud en sí está mal (error de validación, campo requerido faltante)
404: El recurso no existe (ID no encontrado)
422: El formato de la solicitud es correcto pero no se puede procesar

Preguntale a Claude Code “¿debo devolver 404 o 400 acá?” y te va a dar la respuesta correcta.

Error 3: Guardar todo en memoria

El código de esta guía usa un array en memoria para propósitos de demostración. Los datos desaparecen cuando reiniciás el servidor. En producción necesitás una base de datos como PostgreSQL o MongoDB. Solo decile a Claude Code “guardá esto en SQLite en lugar de en memoria” y se encarga de la migración.

---

Próximos pasos

Una vez que dominás los fundamentos de REST API, probá esto:

Paso	Qué hacer
Base de datos	SQLite → PostgreSQL (con Prisma)
Autenticación	Agregar autenticación con JWT
Tests	Escribir tests de API con vitest
Deploy	Publicar en Vercel / Cloudflare Workers

Para todo esto, solo decile a Claude Code “agregá X” y la base estará lista en minutos. Construí algo que funcione primero — ese es el camino más rápido.

Artículos relacionados

• Diseño, implementación y testing de REST API con Claude Code a toda velocidad
• Guía completa para principiantes de Claude Code
• Mejores prácticas de seguridad con Claude Code