Arquitectura de APIs REST: 7 prácticas para que tu backend no se caiga en producción

La mayoría de APIs fallan en producción no por falta de features, sino por decisiones de arquitectura que nadie tomó a propósito. Estas son las siete prácticas que separan una API que aguanta tu primer pico real de tráfico de una que se cae con el Black Friday.

1. Versiona la API desde el primer endpoint

Un prefijo como /api/v1/ cuesta nada agregar hoy y evita romper a todos tus clientes (web, móvil, integraciones) el día que necesites cambiar un contrato.

2. Valida en el borde, no en el medio

Toda entrada externa se valida antes de tocar lógica de negocio — con una librería de esquemas (Zod, Yup), no con ifs sueltos repartidos por el código.

const OrderSchema = z.object({
  items: z.array(ItemSchema).min(1),
  customerId: z.string().uuid(),
});

const body = OrderSchema.parse(await req.json());

3. Códigos de estado HTTP consistentes

201 al crear, 204 al borrar sin contenido, 409 en conflictos, 422 en validación fallida. Un cliente que consume tu API debería poder tomar decisiones solo con el status code, sin parsear el mensaje de error.

4. Autenticación y autorización separadas

Autenticación responde '¿quién eres?'. Autorización responde '¿puedes hacer esto?'. Mezclarlas en un mismo middleware es la forma más común de terminar con un endpoint que filtra datos que no debería.

5. Rate limiting antes de que lo necesites

Un endpoint sin límite de tasa no solo es vulnerable a abuso — un solo cliente mal configurado (un cron mal hecho, un frontend con un loop) puede tumbar tu backend sin que nadie ataque nada.

6. Idempotencia en operaciones críticas

Si un pago se reintenta por un timeout de red, la segunda llamada no debería cobrar dos veces. Una clave de idempotencia (Idempotency-Key) en el header resuelve esto sin lógica compleja en cada endpoint.

7. Logging y observabilidad desde el día uno

Cuando algo falla en producción a las 2am, la pregunta no es 'qué pasó' sino '¿tengo cómo saberlo?'. Logs estructurados con un ID de correlación por request son la diferencia entre un diagnóstico de cinco minutos y una noche entera adivinando.

Ninguna de estas prácticas es exótica — son decisiones de arquitectura documentadas que cuestan lo mismo implementar bien desde el inicio que mal, y son exactamente lo que revisamos cuando entregamos una API a un cliente.