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

Separación clara de los cambios disruptivos y no disruptivos

Atlas incorpora todas las nuevas funciones con cambios importantes en una nueva versión del recurso. La versión estable actual del recurso aún incluye funciones con cambios importantes. Cuando Atlas incorpora una nueva versión del recurso, puede seguir usándola hasta que quede completamente obsoleta mientras desarrolla y prueba la nueva versión del recurso de API.

Periodos de soporte extendido y descontinuación

Atlas desaprueba y luego remueve versiones de recursos solo cuando introduce una nueva versión estable del recurso API. 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 con versiones (v2), los puntos finales de la API de administración de Atlas pasan por previewy stable, deprecated, y sunset etapas 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 endpoints 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 puntos finales 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 recurso en este estado solo se actualiza con cambios permanentes.

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íe una solicitud al recurso e incluya lo siguiente como encabezado de aceptación HTTP:

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

donde el valor de <yyyy-mm-dd> es la fecha de lanzamiento del punto final tal como aparece en la documentación y el registro de cambios.

Atlas returns Código de respuesta de error406 no aceptable si su solicitud omite o especifica una versión de recurso que no existe en el encabezado.

deprecated

Atlas desactualiza automáticamente una versión de un recurso cuando introduce una nueva versión estable. Atlas publica una nueva versión estable cuando introduce cambios importantes 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

Puede seguir enviando solicitudes a versiones anteriores del recurso del punto de conexión hasta que se eliminen. Sin embargo, debe migrar a la versión más reciente del recurso lo antes posible para evitar interrupciones cuando se eliminen versiones anteriores. Para obtener más información sobre la migración a una nueva versión del recurso, consulte Migrar a la API de administración de Atlas con nueva versión.

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 "Desactivado".

Ciclo de vida de un recurso API ilustrado

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

haga clic para ampliar

La ilustración anterior muestra lo siguiente:

Puntos finales deAPI

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 API, si la versión cuenta con un endpoint correspondiente de la API de administración de Atlas con versiones (v2) y la fecha de lanzamiento del recurso versionado de la API de administración de Atlas (v2). Ten en cuenta que un equivalente de v1.0 en la API de administración de Atlas sin versiones está representado por 2023-01-01 en la API de administración de Atlas con versión, la cual ya está obsoleta.