Evolucionar APIs para apps móviles y socios: versiones, compatibilidad y retirada

EN BREVE: Un sitio web se puede actualizar cuando se quiera; una app instalada en los teléfonos de los usuarios y el sistema de un socio, no. Una vez publicada una API, conviene asumir que sus clientes pueden tardar mucho en actualizar. Nuestras reglas: los cambios compatibles van en la versión existente y los incompatibles en una nueva; la versión antigua se declara obsoleta y se mide su uso por cliente; se retira solo cuando el uso lo permite; y el contrato vive en un archivo que la CI comprueba.

Diagrama del ciclo de vida de una versión de API. /v1 está activa y solo recibe cambios aditivos; un cambio incompatible abre /v2; después /v1 se declara obsoleta con las cabeceras Deprecation y Sunset y finalmente se retira devolviendo un error claro. Debajo: medición de uso de /v1 por versión de app y clave de socio, con retirada solo cuando el uso lo permita; y un archivo de contrato (OpenAPI) comparado en CI con la última versión publicada, donde un cambio incompatible fuera de una versión nueva falla.
Figura 1. Una versión mayor de activa a obsoleta y a retirada. La retirada sigue al uso, no al calendario.

1.0 Qué cuenta como compatible

Cambio¿Compatible?
Nuevo campo opcional en la petición, nuevo campo en la respuestaSí, siempre que los clientes ignoren los campos desconocidos
Nuevo endpointSí
Eliminar o renombrar un campo, cambiar su tipoNo
Convertir un campo opcional en obligatorioNo
Añadir un valor a una enumeraciónDepende de cómo traten los clientes los valores desconocidos; por prudencia, tratarlo como incompatible
Cambiar códigos de error u orden por defectoSuele tratarse como compatible, pero rompe a los clientes que dependen de ello

En las dos últimas filas es donde ocurren los incidentes. Desde la primera versión, nuestras pautas para clientes exigen mostrar algo razonable ante un valor de enumeración desconocido en lugar de fallar.

2.0 Dónde va la versión

Un segmento de ruta como /v1/ es lo más visible y funciona bien con logs, enrutado en el gateway y cachés, así que es nuestra opción por defecto. Una cabecera parece más limpia, pero es fácil pasarla por alto al depurar. Esté donde esté, la versión solo cambia ante un cambio incompatible; no sigue el número de versión del producto.

Dentro de una versión mayor, el servidor necesita a veces pequeñas diferencias de comportamiento según la versión del cliente. Haga que los clientes envíen la versión de la app en una cabecera y decida en el servidor, en lugar de crear una sucesión de versiones menores de la API.

3.0 El contrato es un archivo

Describa la API en un archivo como OpenAPI y guárdelo en el repositorio. La CI hace dos cosas: compara el cambio con el contrato de la última versión publicada y hace fallar la compilación ante un cambio incompatible que no esté en una versión nueva, y ejecuta pruebas de contrato para comprobar que la implementación coincide con la descripción.

En las APIs para socios, el archivo de contrato es la fuente de la guía para desarrolladores, no un documento que se mantiene aparte. Dos documentos escritos por separado acaban contradiciéndose.

4.0 Obsolescencia y retirada

  1. Al publicar una versión nueva, las respuestas de la antigua llevan las cabeceras Deprecation y Sunset (RFC 9745, RFC 8594) y la documentación indica la fecha de retirada.
  2. Medir el uso de la versión antigua por cliente: qué versiones de app y qué claves de socio siguen llamando.
  3. En móvil, añadir una versión mínima admitida: el servidor la publica y las apps más antiguas piden al usuario que actualice.
  4. Retirar solo cuando el uso sea aceptablemente bajo. Tras la retirada, devolver un código de error claro con instrucciones de actualización en lugar de un 404 a secas.

La fecha de retirada debe tener en cuenta la revisión de las tiendas de apps y los hábitos de actualización de los usuarios, y los socios necesitan tiempo para desarrollar, probar y desplegar por su parte.

5.0 Idempotencia y reintentos

En redes móviles los reintentos son lo normal. Los endpoints de creación aceptan una clave de idempotencia: el cliente genera una por operación y, durante un tiempo, el servidor devuelve el mismo resultado para la misma clave. Problemas como un pedido enviado dos veces quedan frenados en el propio protocolo.

Para diseñar APIs para una app o para socios, o para poner orden en una API que se ha descontrolado, consulte Web, nube y gestión de dispositivos o hable de un proyecto con nosotros.

Referencias

Preguntas frecuentes

¿Los endpoints que solo usa nuestro propio front end web necesitan tanto rigor?

Un front end web que se despliega y se revierte junto con el backend se puede tratar con más flexibilidad, siempre que la comprobación del contrato siga ejecutándose. En cuanto un cliente no pueda desplegar al mismo ritmo que el servidor, como una app móvil, un miniprograma o un sistema externo, se aplican las reglas de esta nota.

¿Con GraphQL deja de hacer falta versionar?

La convención en GraphQL es no usar versiones y evolucionar añadiendo campos y marcando los antiguos como obsoletos, que es la misma disciplina de compatibilidad con otra forma. Antes de eliminar un campo hay que saber igualmente quién lo sigue consultando.

¿Cuánto tiempo hay que mantener una versión antigua?

Depende de lo rápido que actualicen los usuarios y de los ciclos de despliegue de los socios. Decidimos según el uso real y anunciamos la fecha de retirada al publicar la versión nueva, para que los clientes puedan planificarla.

Hemos refactorizado por dentro. ¿Debe cambiar también la API pública?

La API describe un compromiso hacia fuera, no la estructura interna. Hacer la correspondencia en el servidor y mantener estable el contrato externo suele ser la forma más barata de pasar por una refactorización interna.