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:

Anuncio: Informamos sobre la deprecación a través de nuestro changelog y notificaciones por email.
Marcado de Deprecación: Los endpoints obsoletos recibirán un tag DEPRECATED, junto con la fecha prevista de eliminación.
Período de Transición: Otorgamos un tiempo de gracia (generalmente 6 meses) para permitir la migración a alternativas.
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