Reglas de la API

Las reglas de la API HTTP mantienen los backends de Node predecibles para clientes, BFFs e integraciones de socios entre servicios.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

app.get("/invoices", async (req, res) => {
  const limit = Math.min(Number(req.query.limit ?? 20), 100);
  const cursor = req.query.cursor as string | undefined;
  const page = await listInvoices({ limit, cursor });
  res.json({ data: page.items, nextCursor: page.nextCursor });
});
 
app.post("/invoices", async (req, res) => {
  const key = req.headers["idempotency-key"];
  if (!key) return res.status(400).json({ error: { code: "missing_idempotency_key", message: "required" } });
  // ...
});

Cuándo usarlo:

• APIs HTTP REST o JSON públicas consumidas por web/móvil/socios.
• Múltiples equipos implementan servicios que los clientes tratan de manera uniforme.
• Las mutaciones de pago, pedido o facturación necesitan reintentos seguros.

Ejemplo de trabajo

// src/errors/http-error.ts
export class HttpError extends Error {
  constructor(
    public status: number,
    public code: string,
    message: string,
  ) {
    super(message);
  }
}
 
export function errorHandler(err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) {
  if (err instanceof HttpError) {
    return res.status(err.status).json({ error: { code: err.code, message: err.message } });
  }
  res.status(500).json({ error: { code: "internal_error", message: "unexpected error" } });
}

// src/routes/invoices.ts
app.get("/v1/invoices", async (req, res, next) => {
  try {
    const limit = Math.min(Math.max(Number(req.query.limit ?? 20), 1), 100);
    const result = await repo.list({ limit, cursor: req.query.cursor as string | undefined });
    res.json({ data: result.rows, nextCursor: result.nextCursor });
  } catch (e) {
    next(e);
  }
});
 
app.post("/v1/invoices", async (req, res, next) => {
  try {
    const idempotencyKey = req.headers["idempotency-key"];
    if (typeof idempotencyKey !== "string") {
      throw new HttpError(400, "missing_idempotency_key", "Se requiere el encabezado Idempotency-Key");
    }
    const existing = await repo.findByIdempotencyKey(idempotencyKey);
    if (existing) return res.status(200).json({ data: existing });
    const created = await repo.create({ ...req.body, idempotencyKey });
    res.status(201).json({ data: created });
  } catch (e) {
    next(e);
  }
});

Lo que esto demuestra:

• Envoltura de éxito uniforme { error: { code, message } } y { data: ... }.
• Paginación con limit y nextCursor limitados.
• POST idempotente devuelve 200 en reintentos, 201 en la primera creación.

Análisis Profundo

Cómo funciona

• El prefijo de versión /v1/ permite cambios importantes en /v2/ sin interrupciones silenciosas del cliente.
• El code de error es legible por máquina; el message es seguro para humanos (sin rastros de pila).
• Las claves de idempotencia almacenadas con un índice único evitan cargos duplicados.
• 409 Conflict para conflictos de estado (factura ya cancelada).

Guía de códigos de estado

Notas de TypeScript

• Comparte tipos de respuesta en packages/contracts para consumidores de monorepos.
• Los errores de análisis de Zod se asignan a 400 con code: "validation_error".

Errores comunes

• Diferentes formas de error por ruta - Los clientes no pueden analizar de forma fiable. Solución: solo middleware de error global.
• limit=999999 ilimitado - DB OOM. Solución: límite máximo de 100 en el servidor siempre.
• Idempotencia solo en la documentación - Los reintentos duplican el cargo. Solución: restricción única de DB en la clave.
• Devolver 200 con cuerpo de error - Rompe la semántica HTTP. Solución: códigos de estado adecuados.
• Filtrar IDs internos en errores - postgres uuid constraint en el mensaje. Solución: mensaje genérico, detalles solo en los registros.

Alternativas

Preguntas frecuentes

Relacionado

• Lista de verificación de reglas del proyecto Node - reglas 11-13
• Reglas de seguridad - validación en el límite
• Reglas de registro y observabilidad - registra el ID de solicitud con errores

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.