Los 6 patrones
Cada uno con su porqué de negocio, implementado en NestJS.
- Versionado desde el día uno: todas las rutas nacen con
/v1y los breaking changes van a/v2. Ponerlo cuesta cinco minutos; migrar clientes de una API sin versionar cuesta semanas y favores. - Idempotencia en operaciones críticas: pagos, pedidos y altas exigen un header
Idempotency-Key, de modo que un reintento jamás duplica un cobro. - Paginación siempre: toda colección se devuelve paginada con un límite máximo; la lista que hoy son 50 registros mañana son 50.000 y tumba el servidor.
- Errores consistentes (RFC 9457): un único formato de error en toda la API, con códigos HTTP correctos y sin detalles internos; un error bien diseñado se resuelve sin abrir ticket.
- Rate limiting desde el principio: límites por cliente y respuesta
429conRetry-After, antes del primer susto con un bot o un scraper. - Contrato documentado (OpenAPI): especificación generada desde el código, versionada y validada en CI; si no está documentado, no existe.
Dos ejemplos: el versionado por URI viene de serie y el rate limiting son diez líneas con @nestjs/throttler.
// main.ts
import { VersioningType } from '@nestjs/common';
const app = await NestFactory.create(AppModule);
app.enableVersioning({
type: VersioningType.URI,
defaultVersion: '1',
});// app.module.ts
import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
@Module({
imports: [
ThrottlerModule.forRoot([{ ttl: 60_000, limit: 100 }]), // 100 req/min
],
providers: [{ provide: APP_GUARD, useClass: ThrottlerGuard }],
})
export class AppModule {}Preguntas frecuentes
¿Por qué versionar una API desde el primer día?
Porque cuando llega el primer breaking change ya suele haber varios consumidores en producción; prefijar las rutas con /v1 evita migrar clientes bajo presión.
¿Qué diferencia hay entre idempotencia y rate limiting?
La idempotencia evita que un reintento duplique una operación crítica; el rate limiting evita que un cliente sature la API. Son complementarios.
Datos curiosos
- REST se definió en la tesis doctoral de Roy Fielding en el año 2000; Fielding es también coautor de la especificación HTTP.
- El código 429 Too Many Requests no existió hasta 2012; lo introdujo el RFC 6585.
- El código 418 "I'm a teapot" nació como broma en el RFC 2324 de 1998 y muchos frameworks aún lo implementan.
- NestJS lo creó Kamil Myśliwiec en 2017 inspirándose en la arquitectura modular de Angular, pese a ser un framework de backend.
- "Idempotente" viene de las matemáticas: acuñó el término Benjamin Peirce en el siglo XIX.
¿Y si tu API ya está en producción?
Si tu sistema ya está funcionando y no cumple alguno de estos puntos, la buena noticia es que ninguno exige rehacer nada: todos se pueden incorporar de forma incremental. La menos buena es que cuanto más tarde, más caro.
En Pablo Abreu hacemos diagnósticos técnicos gratuitos: revisamos tu API o tu sistema, te decimos qué está bien, qué es urgente y qué puede esperar — con claridad y sin adornos.