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

Separación clara entre cambios importantes y no importantes

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 desactualiza y elimina las versiones de recursos solo cuando introduce una nueva versión estable de la API. Atlas mantiene la compatibilidad con la versión anterior del recurso para su uso 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 con versiones (v2), los puntos finales de la API de administración de Atlas pasan por preview, stable, deprecated y sunset etapas del ciclo de vida.

preview

Atlas admite endpoints en este estado únicamente para fines de evaluación, prueba y desarrollo. No utilice endpoints de la API de Administración de Atlas en versión preliminar en su entorno de producción, ya que podrían incluir cambios importantes y permanentes. Los endpoints de la API de Administración de Atlas en versión preliminar también tienen un breve periodo de desuso de aproximadamente 30 días o menos, tras el cual podrían pasar al estado stable o deprecated.

Para utilizar los puntos finales de API en la 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 regresa 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 las versiones obsoletas de recursos en el encabezado de respuesta de las solicitudes. Atlas admite las primeras versiones de la API de administración de Atlas (2023-01-01 y 2023-02-01) durante veinticuatro meses después de su desuso. Posteriormente, Atlas admite cualquier versión obsoleta futura de recursos para su uso en su entorno de producción durante doce meses antes de eliminarla automáticamente.

Ejemplo

A continuación se muestra un ejemplo de encabezado 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 ilustrado de los recursos de API

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 puntos de conexión de la API de administración de Atlas sin versión, Atlas introdujo cambios nuevos e importantes en la misma versión. A partir de la API de administración de Atlas versionada (v2), Atlas introduce cambios importantes solo en una nueva versión del recurso. Atlas continúa introduciendo cambios permanentes en la versión stable existente. Utilice la fecha de lanzamiento de un recurso para enviar una solicitud a una versión específica de un punto de conexión de la API de administración de Atlas versionada (v2).

La siguiente tabla muestra las versiones de los puntos finales de la API heredada, si la versión tiene un punto final correspondiente de la API de Administración de Atlas versionada (v)2 y la fecha de lanzamiento del recurso de la API de Administración de Atlas versionada2 (v). Tenga en cuenta que el equivalente de v1.0 en la API de Administración de Atlas sin versionar se representa mediante 2023-01-01 en la API de Administración de Atlas versionada, que ahora está obsoleta.