Saltar al contenido principal
Migo Docs

Versionado de la API

Estrategia de versionado​

Migo prefiere la evolución aditiva y retrocompatible por encima de saltos de versión forzados. La mayoría de los cambios salen en su lugar, sin una nueva versión. Donde existe un segmento de versión, este forma parte de la ruta.

  • Middleware (migo-api) usa versionado de ruta por servicio: algunas rutas de servicio llevan el prefijo /api/v1/ (por ejemplo /api/v1/subscriptions/...), otras llevan solo /v1/ (/v1/services/...), y otras — incluyendo el punto de entrada de link de pago POST /transactions — se sirven en la raíz sin segmento de versión. Usa siempre la ruta exacta que se muestra en la referencia de la API Middleware y en las recetas de este portal; no asumas que un prefijo /v1/ está presente (o ausente) en todas las rutas.
  • Wallet Gateway (ali-api-gw-rest) hoy no está versionado — no hay segmento de versión en sus rutas. Trata el contrato actual como la línea base.

Usa la Referencia de API como fuente de verdad para la ruta en vivo de cada endpoint.

Qué cuenta como cambio incompatible​

Incompatible (se anuncia con anticipación, puede introducir una nueva ruta versionada):

  • Eliminar un endpoint
  • Eliminar un campo de respuesta
  • Cambiar el tipo de un campo de solicitud o de respuesta
  • Agregar un nuevo campo requerido en la solicitud
  • Cambiar patrones de URL o verbos HTTP
  • Endurecer validaciones que antes aceptaban entradas válidas
  • Cambiar los requisitos de autenticación

No incompatible (sale en su lugar, sin nueva versión):

  • Agregar un nuevo endpoint
  • Agregar un campo opcional en la solicitud
  • Agregar un nuevo campo de respuesta
  • Agregar un nuevo valor de enum (los clientes deben ignorar los valores desconocidos — ver abajo)
  • Mejoras de rendimiento
  • Correcciones de errores que hacen que el endpoint se ajuste a su documentación

Expectativas del cliente​

Para consumir las APIs de Migo de forma resiliente:

  1. Ignora los campos de respuesta desconocidos. Aparecerán nuevos campos en respuestas existentes.
  2. Ignora los valores de enum desconocidos. Trata los valores desconocidos como "otro" en lugar de fallar.
  3. Nunca dependas de comportamiento no documentado. Si no está en la especificación OpenAPI, puede cambiar sin previo aviso.
  4. Suscríbete al Changelog. Los anuncios de cambios incompatibles aparecen ahí con más de 90 días de anticipación.

Cómo se realizaría una migración​

Si un cambio incompatible llegara a requerir una nueva ruta versionada, la secuencia prevista es:

  1. Sale la nueva ruta y se documenta en la Referencia de API.
  2. Se publica una guía de migración en el Changelog.
  3. La ruta reemplazada se anuncia como deprecada en el Changelog.
  4. La ruta reemplazada se retira solo después de que esa ventana cierre.

Completa tu migración dentro de la ventana anunciada. El soporte está disponible en support@migopayments.com.