Descripción general de la API de Administración versionada de Atlas

Separación clara de los cambios disruptivos y no disruptivos

Atlas introduce nuevas funcionalidades con cambios incompatibles en cada nueva versión del recurso. La versión estable actual del recurso aún incluye funcionalidades con cambios que no afectan a la compatibilidad. Cuando Atlas lanza una nueva versión del recurso, puede seguir utilizando la versión estable actual hasta que se desactive por completo, mientras desarrolla y realiza pruebas con la nueva versión de la API.

Periodos de soporte extendido y descontinuación

Atlas solo descontinúa y luego elimina versiones de recursos cuando introduce una nueva versión estable de la API. Atlas continúa brindando soporte para la versión anterior del recurso en su entorno de producción durante un máximo de doce meses, lo que le da tiempo para planificar y ejecutar la migración a la siguiente versión.

Ciclo de vida de la API de administración de Atlas versionada

A partir de la API de administración de Atlas versionada (v2), los endpoints de la API de administración de Atlas pasan por las etapas de preview, stable, deprecated y sunset en el ciclo de vida.

preview

Atlas soporta endpoints en este estado solo para fines de evaluación, pruebas y desarrollo. No uses los puntos finales de la API de Administración de Atlas en vista previa en tu entorno de producción, ya que los puntos finales en versión preliminar podrían incluir cambios disruptivos y no disruptivos. Los puntos finales de la API de Administración de Atlas en vista previa también tienen una corta ventana de desaprobación de aproximadamente 30 días o menos, después de lo cual los puntos finales podrían pasar a otro estado stable o deprecated.

Para utilizar los puntos finales de la API en vista previa, envíe una solicitud al recurso e incluya el siguiente encabezado HTTP:

Accept: application/vnd.atlas.preview+json

stable

Atlas admite endpoints estables para su uso en entornos de producción. Atlas proporciona documentación, con registros de cambios, para todos los endpoints estables. Una versión de un recurso en este estado solo se actualiza con cambios no disruptivos.

Cuando Atlas introduce cambios disruptivos en los endpoints, crea una nueva versión de recurso. Cuando se libera una nueva versión de recurso, Atlas también desaprueba automáticamente la versión estable actual de ese recurso. Atlas expone todos los recursos heredados (v1.0 y v1.5) Recursos de la API de administración de Atlas en su primer lanzamiento el 2023-02-01 en estado estable. Atlas soporta la primera versión (2023-01-01 y 2023-02-01) de la API de administración de Atlas versionada durante 24 meses tras su desaprobación. Tenga en cuenta que la versión de recurso /clusters 2023-01-01 (y el equivalente del recurso /v1.0/clusters) está marcada como obsoleta con una ventana de desaprobación de dos años.

Para utilizar las API de administración de Atlas en este estado, envía una solicitud al recurso e incluye lo siguiente como encabezado HTTP Accept:

Accept: application/vnd.atlas.<yyyy-mm-dd>+json

donde el valor para <yyyy-mm-dd> es la fecha de lanzamiento del endpoint según se indica en la documentación y en el registro de cambios.

Atlas devuelve el código de respuesta de error 406 Not Acceptable si su solicitud omite o especifica una versión de recurso que no existe en el encabezado.

deprecated

Atlas deprecia automáticamente una versión de un recurso cuando Atlas introduce una nueva versión estable del recurso. Atlas lanza una nueva versión estable cuando introduce cambios disruptivos en un recurso existente.

Atlas le notifica sobre versiones de recursos obsoletas en el encabezado de respuesta de las solicitudes. Atlas es compatible con las primeras versiones de la API de administración de Atlas (2023-01-01 y 2023-02-01) durante veinticuatro meses después de la obsolescencia. Posteriormente, Atlas admite cualquier versión obsoleta de recursos para su uso en su entorno de producción durante doce meses antes de removerlas automáticamente.

Ejemplo

A continuación se muestra un ejemplo de cabecera de respuesta para una solicitud a un recurso obsoleto programado para su eliminación en el futuro.

Deprecation: Wed, 1 Feb 2023 00:00:00 GMT
Sunset: Sun, 1 Jun 2025 00:00:00 GMT

Puedes seguir enviando solicitudes a versiones anteriores del recurso en el endpoint hasta que se eliminen. Sin embargo, debes migrar a la última versión de recursos lo antes posible para evitar interrupciones cuando se eliminen las versiones antiguas de recursos. Para obtener más información sobre cómo migrar a una nueva versión de recursos, consulta Migración a la nueva API de administración de Atlas con versiones.

sunset

Atlas elimina automáticamente las versiones de recursos después de un año de desuso. Si envía una solicitud a una versión de recurso eliminada, Atlas devuelve el código de respuesta de error 410 Gone.

Ciclo de vida de un recurso API ilustrado

El siguiente ejemplo ilustra el ciclo de vida de un recurso y su impacto en el versionado.

haga clic para ampliar

La ilustración anterior muestra lo siguiente:

Puntos finales de laAPI

Para los endpoints heredados sin versión de la API de administración de Atlas, Atlas introdujo cambios nuevos y disruptivos en la misma versión. A partir de la API de administración de Atlas versionada (v2), Atlas solo introduce cambios disruptivos en una nueva versión de recursos. Atlas sigue incorporando cambios no disruptivos a la versión existente de stable. Utiliza la fecha de lanzamiento de un recurso para enviar una solicitud a una versión específica de un endpoint de la API de administración de Atlas versionada (v2).

La siguiente tabla muestra las versiones heredadas de los puntos finales de la API, si cada versión tiene un punto final correspondiente en la API de administración de Atlas (v2) y la fecha de lanzamiento del recurso de la API de administración de Atlas (v2). Cabe destacar que el equivalente de v1.0 en la API de administración de Atlas sin versiones se representa mediante 2023-01-01 en la API de administración de Atlas con versiones, que ahora está obsoleta.