Ciclo de Vida y Versionado de la API de Akua

En Akua, nuestra API evoluciona de manera continua, incorporando nuevas funcionalidades y mejoras sin comprometer la estabilidad de las integraciones existentes. Utilizamos un sistema de versionado basado en versiones mayores (/v1, /v2, etc.), lo que significa que cualquier cambio disruptivo dará lugar a una nueva versión, mientras que las actualizaciones menores se implementarán dentro de la versión actual.

Este documento describe cómo gestionamos los cambios en la API, asegurando compatibilidad hacia atrás y proporcionando información clara sobre actualizaciones, deprecaciones y mejoras.

Principios de Versionado

• Evolución Incremental: Mejoramos la API dentro de la versión actual (/v1), agregando nuevas funciones sin afectar la compatibilidad con integraciones existentes.
• Transparencia: Comunicamos los cambios con antelación a través de nuestro changelog y notificaciones dirigidas.

Cambios Compatibles y No Compatibles

Al actualizar la API, es importante distinguir entre cambios no disruptivos (compatibles con versiones anteriores) y cambios disruptivos (requieren una nueva versión de la API).

Cambios Compatibles con Versiones Anteriores

Los siguientes cambios no afectan la funcionalidad de las integraciones actuales y no requieren migraciones:

• Agregar nuevos endpoints sin modificar los existentes.
• Añadir nuevos parámetros opcionales a las solicitudes.
• Agregar nuevas propiedades en las respuestas sin afectar los valores existentes.
• Cambiar el orden de los campos JSON en las respuestas.
• Introducir nuevos códigos de error sin eliminar los actuales.
• Optimizar la API para mejorar tiempos de respuesta y estabilidad sin modificar su comportamiento.

Cambios No Compatibles con Versiones Anteriores (Breaking Changes)

Estos cambios pueden afectar las integraciones existentes y requieren una nueva versión (/v2, /v3, etc.):

• Eliminar o renombrar endpoints existentes.
• Modificar la estructura de las URLs (por ejemplo, cambiar /merchants/{id} a /accounts/{id}).
• Modificar el formato de las solicitudes o respuestas, como eliminar campos requeridos o cambiar tipos de datos.
• Cambiar los requisitos de autenticación o permisos de acceso.
• Eliminar códigos de error utilizados en la gestión de respuestas de los clientes.

Si se introduce un cambio disruptivo, se creará una nueva versión mayor de la API y se notificará a los clientes con suficiente antelación.

Política de Deprecación

Para garantizar una transición fluida, seguimos un proceso estructurado de deprecación cuando una funcionalidad o endpoint queda obsoleto:

1. Anuncio: Informamos sobre la deprecación a través de nuestro changelog y notificaciones por email.
2. Marcado de Deprecación: Los endpoints obsoletos recibirán un tag DEPRECATED, junto con la fecha prevista de eliminación.
3. Período de Transición: Otorgamos un tiempo de gracia (generalmente 6 meses) para permitir la migración a alternativas.
4. Eliminación: Finalizado el período de transición, los endpoints obsoletos son retirados de la API. Se proveerán guías de migración si es necesario.

Entornos de Prueba y Feedback

Para minimizar el impacto en las integraciones y recibir retroalimentación anticipada, ofrecemos:

• Entorno Sandbox: Un entorno de prueba idéntico al de producción donde se pueden validar cambios antes de su implementación.
• Canales de Feedback: Recolectamos opiniones sobre cambios a través de nuestro equipo de soporte y documentación colaborativa.
• Funciones Experimentales (EXP): Algunas funcionalidades pueden ser etiquetadas como EXPERIMENTAL, lo que indica que están en fase de validación y pueden sufrir cambios antes de su lanzamiento oficial.

⚠️ Nota: Las funciones EXPERIMENTAL pueden modificarse sin seguir el proceso estándar de deprecación.

Compromiso con la Estabilidad

En Akua, nuestro objetivo es mantener una API confiable y robusta que permita a nuestros clientes operar sin interrupciones. Al seguir esta política, aseguramos un equilibrio entre innovación y estabilidad, brindando la confianza necesaria para desarrollar integraciones escalables y seguras.

📩 Para cualquier consulta sobre nuestra política de versión y evolución de la API, contacta con nuestro equipo de soporte o visita nuestro portal de desarrolladores.

Ejemplo de Solicitud con Versión Específica

Vas a poder especificar la versión de la API de Akua que quieras consumir simplemente definiendola en la url de la misma:

curl 'https://api.akua.la/v1/payments' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer token-documentacion" \
    -X GET