Mejores prácticas de diseño de API

Documenta los cambios importantes como las migraciones de bases de datos: deliberados, revisados y anunciados. Estas prácticas hacen que las API HTTP de Node.js sean predecibles para los integradores.

Cómo usar esta lista

• Revisa cada PR de endpoint público
• CI aplica la diferencia de OpenAPI y la validación de Zod
• Combínalo con Versionado y Deprecación
• Las API de administración internas pueden relajar algunas reglas; documenta qué superficie es pública

A - Recursos y HTTP

• Las URL usan sustantivos y colecciones plurales. /v1/orders, no /getOrders.
• Los métodos HTTP expresan la intención. POST para crear, PATCH para actualización parcial, DELETE para eliminar.
• Códigos de estado correctos. 201 en creación, 204 en eliminación sin cuerpo, 409 en conflicto.
• No hay errores de negocio en cuerpos 200. Usa 4xx/5xx con JSON estructurado.
• Recursos anidados con un máximo de un nivel a menos que el dominio requiera claramente más.

B - Forma de la solicitud y la respuesta

• Envoltorio consistente. { data } en éxito, { error } o Detalles del Problema en fallo.
• Valida la consulta, los parámetros y el cuerpo con Zod en el límite HTTP.
• Documenta cada campo público en OpenAPI. Explícito si es requerido u opcional.
• Usa ISO8601 UTC para las marcas de tiempo en cadenas JSON.
• Dinero como unidades menores enteras (centavos) o decimal de cadena; elige uno para toda la organización.

C - Errores

• code estable por tipo de error. Los clientes nunca analizan el message en inglés.
• RFC 9457 Problem Details para API B2B públicas.
• Middleware de error central mapea los errores de dominio a HTTP.
• Incluye requestId en la carga útil del error para la correlación de soporte.
• No hay rastros de pila en las respuestas JSON de producción.

D - Paginación, filtrado, rendimiento

• Paginación por cursor por defecto para listas públicas. Limita limit a 100.
• Lista blanca de parámetros de consulta de filtro. Rechaza filtros desconocidos con 400.
• Los índices coinciden con las columnas de filtro y ordenación. Revisa los planes de consulta para los endpoints de lista.
• Encabezados de límite de tasa en rutas de lista/búsqueda costosas.
• Exportación asíncrona para datos masivos - no listas síncronas ilimitadas.

E - Versionado y compatibilidad

• Prefijo de versión de ruta /v1. Nueva versión principal con cambios importantes -> /v2.
• Encabezados de Deprecación y Caducidad en versiones antiguas con fecha de publicación.
• Guía de migración para cada cambio importante vinculada desde el registro de cambios.
• Especificación OpenAPI por versión principal en artefactos de CI.
• Solo cambios aditivos dentro de una versión principal a menos que sea una corrección de seguridad de emergencia.

F - Seguridad y operaciones

• Autentica antes de analizar el cuerpo en cargas útiles grandes cuando sea posible.
• Idempotency-Key en pagos POST y creaciones con almacenamiento de deduplicación en el servidor.
• Lista de permitidos explícita de CORS - no * con credenciales.
• Límites de tamaño de solicitud a través de express.json({ limit }) o bodyLimit de Fastify.
• Endpoints de salud separados de la API versionada en /health/live y /health/ready.

Preguntas frecuentes

Relacionado

• Conceptos básicos de diseño de API - patrones introductorios
• OpenAPI y Swagger - fuente del contrato
• Estándares de respuesta de error - Detalles del problema
• Paginación y filtrado - endpoints de lista
• Versionado y Deprecación - política de caducidad

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.