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

Separación clara de los cambios disruptivos y no disruptivos

Atlas presenta todas las nuevas funcionalidades con cambios disruptivos en una nueva versión de recurso. La versión actual y estable del recurso todavía incluye funcionalidades que contienen cambios no disruptivos. Cuando Atlas introduce una nueva versión de los recursos, puedes seguir utilizando la versión estable actual de los recursos hasta que se haya desaprobado por completo mientras desarrollas y pruebas la nueva versión de los recursos de API.

Periodos de soporte extendido y descontinuación

Atlas deja de usar y luego remueve las versiones de recursos solo cuando introduce una nueva versión estable de API de recursos. Atlas sigue respaldando la versión anterior del recurso para su uso en tu entorno de producción durante hasta doce meses, lo que te brinda tiempo para planificar y ejecutar tu migración a la versión siguiente.

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 usar 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 regresa el 406 No Aceptable código de respuesta de error si tu 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 los recursos después de un año de desuso. Si envías 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.

La ilustración anterior muestra lo siguiente:

Puntos finales de la API

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 del endpoint API, si la versión tiene un endpoint equivalente de la API de administración de Atlas versionada (v2), y la fecha de lanzamiento del recurso versionado de la API de administración de Atlas (v2). Tenga en cuenta que un equivalente de v1.0 en la API de Administración de Atlas no versionada está representado por 2023-01-01 en la API de Administración de Atlas versionada, la cual ahora se encuentra en desuso.