Fuente de verdad
El contrato externo vigente esapi-reference/openapi.json. La documentación explica flujos y decisiones, pero no puede añadir rutas, campos o estados ausentes del runtime y del OpenAPI.
La versión principal se incluye en la ruta, actualmente /integrations/v1.
Cambios compatibles
Se consideran compatibles, sujetos a prueba:- agregar una operación nueva;
- agregar un campo de respuesta opcional;
- agregar un código de error documentado sin cambiar el significado de éxito;
- ampliar un enum cuando los clientes toleran valores desconocidos.
Cambios incompatibles
Requieren una versión nueva y una ventana de migración:- eliminar o renombrar una operación o campo;
- cambiar obligatoriedad, tipo o semántica;
- cambiar el aislamiento de tenant;
- reducir límites por debajo del contrato vigente;
- reutilizar un código de error con otro significado.
Proceso de publicación
En cada cambio:- auditar controladores externos, migraciones, guards y pruebas;
- actualizar OpenAPI y guías en el mismo cambio;
- validar navegación, rutas, servidor, seguridad y ausencia de rutas internas;
- desplegar el runtime antes de anunciar una operación;
- verificar salud, autenticación cerrada y contrato público;
- publicar Mintlify desde
main.