Un pequeño cambio en una respuesta API puede romper un cliente. Revisa el contrato con escenarios de sus consumidores antes de publicar. DOCUMENTA LA PROMESA Para las operaciones importantes, registra método, dirección, parámetros, campos obligatorios, tipos y errores. OpenAPI proporciona un formato para describir API HTTP, pero el archivo no demuestra conformidad de la implementación. Asigna un responsable e incorpora la descripción al proceso de lanzamiento. REVISA CAMBIOS MENOS OBVIOS Eliminar un campo resulta visible. Renombrarlo, convertir un número en texto, añadir un valor de enumeración o cambiar null puede descubrirse solo en el cliente. Incluso un campo opcional nuevo puede fallar ante un analizador estricto. Separa incompatibilidades claras de cambios que requieren probar consumidores concretos. PREPARA EJEMPLOS PEQUEÑOS Usa resultado típico, lista vacía, campo opcional ausente, error de validación y acceso denegado con datos inofensivos. Añade monedas o formatos de fecha admitidos si forman parte del contrato. Ejecuta los ejemplos con versiones cliente mantenidas, no solo con el servidor nuevo. Prueba pagos en el entorno de pruebas del proveedor sin cargos reales. PLANIFICA LA TRANSICIÓN Para cambios incompatibles, acuerda versionado y plazo de migración. Una fecha en una tarea interna no avisa a los usuarios de la API. Registra destinatarios del aviso, documentación actualizada y responsable de observar solicitudes antiguas. Las recomendaciones de Microsoft relacionan versionado y soporte de consumidores; adapta el mecanismo a tu producto. Define una dirección estable para documentación y un subdominio API claro. La estructura del dominio facilita navegar, pero no sustituye la compatibilidad. Guarda los resultados junto al registro de lanzamiento para revisar futuras modificaciones con pruebas y no solo con recuerdos. Imagen: nueva fotoilustración generada con IA para este artículo; escena conceptual, no una fotografía documental. Catálogo de dominios: https://domainevery.com/es/domains Fuentes primarias: https://learn.microsoft.com/en-us/azure/architecture/best-practices/api-design https://spec.openapis.org/oas/latest.html
