Saltar al contenido principal
Home
HexagonalGuru

APIs REST que Envejecen Bien: Contratos, Versionado y Errores

Avatar de HexagonalGuru

HexagonalGuru

APIs REST que Envejecen Bien: Contratos, Versionado y Errores

Tu API funcionaba perfectamente hasta que tuvo un segundo consumidor. El primero era tu propia SPA: la controlabas, la desplegabas a la vez y cualquier cambio se coordinaba en cinco minutos. El segundo es una integración que hiciste con un partner hace dos años. Ahora cada refactor es un ejercicio de arqueología: ¿alguien usa este campo?, ¿qué pasa si cambio este formato?, ¿por qué el partner dice que «desde el martes todo falla»?

La diferencia entre una API que funciona y una API que envejece bien es la diferencia entre pensar en el consumidor de hoy y pensar en el de dentro de tres años. Y casi todo lo que hay que hacer es barato — si se hace desde el principio. Esta guía va de los contratos, el versionado y los errores: las tres piezas que deciden si tu API será un activo o una losa.

El Contrato es la API (No el Código)

Una API es una promesa: «si me pides esto así, te respondo esto otro asá». El código que la implementa puede cambiar todos los días; la promesa, casi nunca. Los consumidores no dependen de tu código: dependen de la forma de tus peticiones y respuestas, de tus códigos de estado y de tus errores.

La consecuencia práctica es el diseño contract-first: el contrato (OpenAPI, normalmente) se escribe antes o a la vez que el código, se revisa como se revisa el código, y los cambios se miran con una pregunta delante: ¿esto rompe a alguien que ya está integrado? Si la respuesta es sí, no es un cambio: es una negociación.

Cambios que Suman y Cambios que Rompen

Cambios seguros y cambios que rompen en una API REST: añadir campos o endpoints es seguro; renombrar o eliminar campos, cambiar tipos o el significado de los errores rompe a los consumidores

La regla de oro de la compatibilidad es que hay dos listas, y conviene tenerlas interiorizadas:

  • Cambios aditivos (casi siempre seguros): añadir un endpoint nuevo, añadir un campo opcional en la respuesta, añadir un parámetro opcional con valor por defecto, añadir un valor nuevo a un enum solo si los consumidores toleran valores desconocidos.
  • Cambios destructivos (rompen): renombrar o eliminar un campo, cambiar su tipo, hacer obligatorio un parámetro que era opcional, cambiar el significado de un código de estado, endurecer una validación que antes pasaba.

La trampa más sutil es la del consumidor tolerante: un cliente JSON robusto ignora los campos que no conoce, así que añadir campos es gratis. Pero si tus consumidores validan el esquema estrictamente, incluso un campo nuevo rompe. Publica tu política de tolerancia en la documentación: «podemos añadir campos sin previo aviso; ignora los que no conozcas» es una frase que evita años de dolor.

Versionado: el Último Recurso, No el Primero

Cuando el cambio destructivo es inevitable, toca versionar. Pero v2 no es una decisión de diseño: es una decisión operativa que multiplica el trabajo — dos contratos que mantener, dos suites de tests, dos documentaciones. Antes de llegar ahí:

  1. Primero, lo aditivo. ¿Puedes añadir el campo nuevo sin quitar el viejo? price_cents nuevo conviviendo con price viejo, con el viejo marcado como deprecated. Es feo durante un tiempo; es mucho más barato que una v2.
  2. Después, la extensión. ¿Un endpoint nuevo en vez de cambiar el viejo? /v1/invoices/{id}/summary nuevo mientras el detalle antiguo sigue intacto.
  3. Solo entonces, la versión. Y cuando llegue: con fecha de deprecación publicada para la antigua, guía de migración concreta y contacto directo con los consumidores conocidos. La versión sin plan de retirada es deuda técnica con nombre bonito.

Sobre el mecanismo (path /v1/, header Accept, query param): importa menos que la coherencia. Elige uno, documéntalo y no lo cambies. El path tiene la ventaja de ser visible y fácil de enrutar y cachear; el header es más «puro» pero invisible en los logs si no lo registras.

Los Errores También son Contrato

Los consumidores escriben código contra tus errores: reintentan, muestran mensajes, deciden. Un error que cambia sin aviso rompe tanta lógica como un campo renombrado. Las reglas que lo evitan:

  • Usa los códigos HTTP con su significado. 400 es petición inválida, 401 no autenticado, 403 sin permiso, 404 no existe, 409 conflicto de estado, 422 válida en formato pero inválida en negocio, 429 demasiadas peticiones. Un 200 con {"error": "..."} en el cuerpo rompe todos los clientes HTTP sensatos del mundo.
  • Formato de error único y documentado. El estándar de facto es Problem Details (RFC 9457): un JSON con type, title, status, detail y un code de máquina estable por tipo de error. El mensaje humano puede cambiar; el código de máquina es contrato.
  • Idempotencia en las escrituras. Si un timeout hace reintentar un POST /payments, ¿se cobra dos veces? Una cabecera Idempotency-Key con la que el servidor deduplica reintentos convierte el fallo de red en no-evento. Es la pieza que más disgustos evita por euro invertido.
  • Errores de validación accionables. «Invalid request» obliga a llamarte. {"code": "VALIDATION_ERROR", "fields": {"email": "must be a valid email"}} permite al consumidor arreglarlo solo.

Lo que Mantiene Joven a una API

Más allá del contrato, cuatro hábitos que marcan la diferencia a los tres años:

  1. Paginación desde el día uno. El listado que hoy devuelve 50 registros mañana devolverá 50.000. Cursor o página, da igual; lo que no da igual es añadirla después, porque cambia la forma de la respuesta y eso rompe.
  2. Tests de contrato. Una suite que verifica que las respuestas siguen cumpliendo el esquema publicado, ejecutada en el CI. Los tests unitarios prueban tu código; los tests de contrato prueban tu promesa.
  3. Documentación viva. Generada del contrato, no escrita a mano en una wiki que se queda vieja el primer mes. Si la doc y el código discrepan, el consumidor cree a la doc — y el bug es tuyo.
  4. Logs de consumo por cliente. Saber quién llama a qué es lo que te permite decidir con datos qué se puede retirar. Sin telemetría de consumo, cada deprecación es un salto de fe — y aquí tu observabilidad se paga sola.

Errores Comunes

  1. Diseñar la API a imagen de la base de datos. Exponer tablas y joins como recursos convierte cada migración de esquema en un cambio destructivo. La API modela el dominio del consumidor, no tus tablas.
  2. La SPA como único consumidor imaginado. «Solo la usa nuestra web» dura exactamente hasta el primer partner, la app móvil o la integración interna. Diseña como si el segundo consumidor ya existiera.
  3. Versiones que nunca mueren. Mantener v1, v2 y v3 a la vez sin fecha de retirada es triplicar el mantenimiento por miedo a una conversación. Deprecar con fecha y aviso es más barato y más profesional.
  4. Errores como excepciones sin forma. Un stack trace en el cuerpo del 500 no ayuda al consumidor y filtra información de tu interior. El error de producción es un documento público: trátalo como tal.
  5. Cambiar el contrato sin contarlo. El changelog de la API es tan obligatorio como el del producto. Cada cambio aditivo se anuncia; cada cambio destructivo se negocia.

En Resumen

Una API que envejece bien es una promesa cuidada: contrato explícito y revisado, cambios aditivos antes que destructivos, versionado como último recurso con plan de retirada, errores con formato estable e idempotencia en las escrituras. Paginación, tests de contrato y documentación generada la mantienen joven. Todo es barato al principio y carísimo después — y el consumidor de dentro de tres años te lo agradecerá, aunque nunca sepa quién eres.

Si tu API ha crecido sin contrato claro y cada cambio es una ruleta, podemos revisarla y proponer un plan de estabilización sin romper a tus consumidores actuales. Hablemos →

Sigue leyendo: REST vs GraphQL: cómo elegir la API correcta para tu proyecto.

  • #apis
  • #rest-api

Artículos relacionados

¿Empezamos?

¿Listo para construir algo que crezca con tu negocio?

Cuéntanos tus objetivos y trazaremos juntos la ruta de diseño, desarrollo y tecnología que te lleve de la visión a resultados medibles.