Conceptos básicos del diseño de API

8 ejemplos para empezar con el Diseño de API para backends de Node.js: 6 básicos y 2 intermedios.

Prerrequisitos

Express 5 o Fastify 5 con análisis de cuerpo JSON y Zod instalados.

npm install express@5 zod

Ejemplos básicos

1. URL orientadas a recursos

GET    /v1/orders
POST   /v1/orders
GET    /v1/orders/:id
PATCH  /v1/orders/:id
DELETE /v1/orders/:id

• Sustantivos en las rutas; los verbos provienen de los métodos HTTP
• Recursos anidados de un solo nivel de profundidad: /v1/orders/:id/items
• Evita las rutas de estilo RPC como /createOrder en las API REST públicas

Relacionado: Versionado y Deprecación - prefijo /v1

2. Sobre JSON consistente

{ "data": { "id": "ord_1", "status": "pending" } }

{ "error": { "code": "ORDER_NOT_FOUND", "message": "Order ord_99 not found" } }

• Las respuestas exitosas envuelven la carga útil en data
• Los errores usan un objeto error con un code estable para los clientes
• Las listas devuelven data como un array más metadatos de paginación

Relacionado: Estándares de respuesta de error - Detalles del problema

3. Códigos de estado correctos

• No devuelvas 200 con { error: ... } en el cuerpo
• 422 es aceptable para la validación semántica si el equipo lo estandariza

4. Validación Zod en el límite

import { z } from "zod";
import express from "express";
 
const createOrderBody = z.object({
  customerId: z.string().uuid(),
  sku: z.string().min(1),
  qty: z.number().int().positive(),
});
 
const app = express();
app.use(express.json());
 
app.post("/v1/orders", (req, res) => {
  const parsed = createOrderBody.safeParse(req.body);
  if (!parsed.success) {
    return res.status(400).json({
      error: { code: "VALIDATION_ERROR", details: parsed.error.flatten() },
    });
  }
  res.status(201).json({ data: { id: crypto.randomUUID(), ...parsed.data } });
});

• El JSON inválido nunca llega a los casos de uso
• Devuelve detalles a nivel de campo para clientes de formularios
• Comparte esquemas con el frontend siempre que sea posible

5. Semántica de PUT/PATCH idempotente

PATCH /v1/orders/ord_1
{ "status": "shipped" }

• PATCH actualización parcial; documenta los campos permitidos
• PUT reemplazo completo cuando lo soportes - raro en las API B2B
• Usa el encabezado Idempotency-Key en los pagos POST (ver intermedio)

6. Vista previa de parámetros de consulta de paginación

GET /v1/orders?limit=20&cursor=eyJpZCI6Im9yZF8xMjMifQ

• Prefiere la paginación por cursor para tablas grandes
• El offset es aceptable para pantallas de administración con conjuntos de datos pequeños

Relacionado: Paginación y Filtrado - cursor vs offset

Ejemplos intermedios

7. Negociación de contenido y solo JSON

app.use((req, res, next) => {
  if (req.method === "POST" && !req.is("application/json")) {
    return res.status(415).json({ error: { code: "UNSUPPORTED_MEDIA_TYPE" } });
  }
  next();
});

• Las API públicas se estandarizan en application/json
• Los webhooks verifican Content-Type y la firma por separado

8. Stub de OpenAPI desde rutas

Documenta las rutas a medida que las implementas.

paths:
  /v1/orders:
    post:
      summary: Create order
      responses:
        "201":
          description: Created

• OpenAPI escrito a mano o generado por código evita la desviación

Relacionado: OpenAPI y Swagger - spec-first vs code-first

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.