Disponibilidad y compatibilidad resuelven problemas distintos. Un endpoint puede devolver HTTP 200 y entregar una estructura que el consumidor ya no entiende. El gobierno de APIs conecta decisiones de diseño, responsables y evidencia de uso para proteger el proceso que depende del servicio.
1) El problema de los cambios no gobernados
Imagina una API de pedidos que acepta una referencia externa opcional. Convertirla en obligatoria puede rechazar solicitudes que ayer eran válidas. El equipo proveedor puede considerar el cambio pequeño; para el consumidor es una interrupción contractual.
- Hacer obligatorio un campo de entrada o cambiar su tipo.
- Reemplazar una lista por un objeto, retirar un campo o cambiar su significado.
- Exigir nuevos scopes, otro mecanismo de autenticación o certificados distintos.
- Reducir cuotas o límites de consumo sin acordar la transición.
Incluso un campo adicional puede afectar a clientes con validación estricta. Evalúa compatibilidad con pruebas de consumidores, no solo con el tamaño del diff. Las políticas descritas en protección de endpoints con API Management también forman parte del comportamiento observable.
2) Define el contrato mínimo antes de publicar
Documenta recursos, métodos, esquemas de entrada y salida, campos obligatorios, códigos de error, paginación, fechas, zonas horarias y reglas de idempotencia. Usa OpenAPI cuando corresponda, junto con ejemplos y criterios de aceptación; el esquema por sí solo no explica todas las reglas de negocio.
Acuerda autenticación, autorización, límites, tiempos de respuesta esperados y soporte. Identifica al owner técnico, al responsable funcional y a los consumidores con un contacto de migración. Una matriz de ownership aclara quién aprueba un cambio y quién responde ante una incompatibilidad.
3) Cuándo crear una versión nueva
Una corrección que mantiene el contrato puede permanecer en la versión existente después de probar regresiones. Un cambio incompatible requiere una nueva versión del contrato o una transición explícita aceptada por todos los afectados. No cambies el comportamiento de v1 y lo anuncies después.
En SAP API Management, una revisión del proxy no equivale a una versión nueva del contrato para consumidores. Planifica una dirección o mecanismo de versionado estable y un período de convivencia. Cambiar solo el número no aísla a v1 si ambas versiones dependen de un backend que dejó de soportarla.
4) Deprecar es un proceso, no apagar un endpoint
- Publica el reemplazo y explica diferencias, fecha objetivo y soporte de migración.
- Notifica a los consumidores identificados y registra su plan y responsable.
- Prueba ambas versiones y observa tráfico real durante la convivencia.
- Investiga llamadas residuales, incluyendo procesos mensuales o esporádicos.
- Aprueba el retiro con evidencia, comunicación final y procedimiento de recuperación.
Marcar una API como deprecada comunica una intención; no demuestra que sus consumidores migraron. Antes de retirar, revisa también certificados, secretos y endpoints compartidos para no romper otra interfaz.
5) Mantén un catálogo mínimo y útil
Por API registra propósito de negocio, versión, estado del ciclo de vida, URL por ambiente, contrato y repositorio, owners, consumidores, dependencias, políticas de acceso y fecha de retiro si aplica. Añade la última prueba de compatibilidad y enlaces a monitoreo y runbooks. Guarda referencias a secretos, nunca sus valores.
6) Monitorea por consumidor y resultado
Relaciona llamadas con una identidad técnica autenticada, como una aplicación cliente; no confíes en un header arbitrario para autorizar acceso. Revisa errores, latencia y rechazos por cuota por consumidor y versión, con una línea base que permita detectar regresiones.
Un Correlation ID de extremo a extremo ayuda a investigar, pero no sustituye la identidad del cliente. Minimiza datos personales en logs y conecta alertas con el plan de continuidad de Integration Suite.
Checklist de liberación
- Contrato revisado y cambio clasificado por compatibilidad.
- Consumidores, owners y comunicación identificados.
- Pruebas de esquema, autorización, errores, límites y regresión aprobadas.
- Dependencias del backend compatibles durante la convivencia.
- Monitoreo por versión y consumidor, ventana y responsable definidos.
- Rollback ensayado y datos ya procesados considerados.
La liberación termina cuando el consumidor sigue logrando su resultado, no cuando el proxy se desplegó. Para profundizar en los mecanismos de la plataforma, consulta API Versioning de SAP y API Revisions.