Diseño de APIs: cuándo romper la pureza por pragmatismo

En teoría, el diseño de APIs REST es limpio, elegante y perfectamente alineado con estándares. En la práctica, los sistemas reales viven bajo presión: tiempos, equipos, negocio y legado. En este artículo vamos a hablar de algo incómodo pero necesario: cuándo romper la pureza es la decisión correcta.

La trampa de la pureza absoluta

Muchos desarrolladores diseñan APIs intentando cumplir cada regla al pie de la letra:

• REST 100% ortodoxo
• Recursos perfectamente modelados
• HTTP verbs usados de forma académica

El problema aparece cuando el costo de la pureza supera el valor que entrega. Ahí es donde una API “correcta” se vuelve difícil de usar, lenta de evolucionar o imposible de mantener.

Pragmatismo no es desorden

Romper la pureza no significa hacer cualquier cosa. Significa priorizar claridad, mantenibilidad y valor por encima del dogma.

Un diseño pragmático:

• Es fácil de entender para otros equipos
• Reduce fricción en el consumo
• Permite evolucionar sin romper todo

Casos reales donde el pragmatismo gana

1. Endpoints orientados a acciones

En teoría, todo debería ser un recurso. En la práctica:

POST /orders/{id}/cancel

Puede ser más claro que forzar un modelo complejo solo para “respetar” REST.

2. Respuestas adaptadas al cliente

Una API que devuelve exactamente lo que el frontend necesita puede romper la “pureza”, pero reduce:

• Lógica duplicada
• Llamadas innecesarias
• Complejidad del cliente

3. Versionado pragmático

Idealmente no versionarías nunca. En realidad, versionar explícitamente:

/api/v1/...

Evita caos, rompe menos clientes y permite avanzar.

Cómo decidir cuándo romper reglas

Hazte estas preguntas antes de hacerlo:

1. ¿Esta decisión simplifica el uso real de la API?
2. ¿Reduce complejidad futura?
3. ¿Es entendible para otros desarrolladores?

Si la respuesta es sí, probablemente no estás rompiendo nada importante.

El criterio es la verdadera arquitectura

Las mejores APIs no son las más puras, sino las que:

• Sobreviven al crecimiento
• Se adaptan al negocio
• Pueden mantenerse sin héroes técnicos

Eso no se logra siguiendo reglas ciegamente, sino aplicando criterio.

Conclusión

La pureza es una guía, no una cárcel. Un buen ingeniero sabe cuándo respetar las reglas y cuándo romperlas conscientemente. En diseño de APIs, el pragmatismo bien aplicado es una señal de madurez técnica, no de ignorancia.