Con la introducción de la API de Administración Atlas con versionado (denominada aquí como /v2), recomendamos migrar de la API de Administración Atlas heredada (denominada como /v1) a la nueva API de Administración Atlas con versionado (/v2).
Introducción a la API de administración de Atlas versionada
La nueva API versionada de Administración de Atlas brinda una experiencia general significativamente mejor para acceder a Atlas programáticamente. La API de administración de Atlas versionada proporciona una experiencia predecible y coherente con los cambios en la API y ofrece mejor visibilidad sobre las nuevas funcionalidades y cambios.
Ciclo de vida de la API de administración de Atlas versionada
Atlas expone una nueva versión de recurso de un API endpoint existente cuando Atlas introduce cambios disruptivos en la versión estable actual del API endpoint. Cuando Atlas expone una nueva versión de un recurso, Atlas desaprueba automáticamente la versión anterior del recurso. Atlas elimina automáticamente la versión obsoleta del recurso doce meses después de su obsolescencia. Aunque Atlas seguirá admitiendo la versión más antigua del recurso para su uso en su entorno de producción durante un máximo de doce meses, debe migrar a la nueva versión del punto final de API lo antes posible. Para obtener más información, consulta el ejemplo en Esquema de versionado.
Ten en cuenta que con la gestión de versiones a nivel de recurso, cada recurso en la API de administración de Atlas versionada puede introducir una nueva versión de forma independiente de otros recursos. Sólo tienes que actuar cuando los recursos que estás utilizando estén obsoletos.
Ejemplo
Supongamos que Atlas introduce algún recurso nuevo en 2023-06-01, pero /backup no tiene ningún cambio disruptivo y se mantiene en 2023-02-01. Debe migrar a 2023-06-01 solo si está utilizando ese recurso. Si no has implementado el recurso, no tienes que realizar ninguna acción.
Atlas admite la versión de recurso obsoleta durante al menos doce meses hasta que se elimine, lo que le brinda tiempo para planificar y realizar la transición a la nueva versión. Puedes ver los cambios en cada nuevo recurso en la historial de cambios de la API y obtener detalles de la versión de la API en la especificación de la API.
Procedimiento
Para migrar a la nueva API de Administración Versionada de Atlas, deberás hacer lo siguiente:
Especifica el número que representa la API con versión en la URL base del recurso.
https://cloud.mongodb.com/api/atlas/<version-number>/
Ejemplo
Considere la siguiente base URL para la versión heredada de un recurso de Atlas Administration API:
https://cloud.mongodb.com/api/atlas/v1.0/
Con la introducción de la API de administración versionada, la base anterior URL indica que estás utilizando recursos que no están versionados. Para enviar una solicitud al recurso de la API de administración atlas versionada (/v2), debe enviar su solicitud a la siguiente URL base:
https://cloud.mongodb.com/api/atlas/v2/
Para obtener información sobre cómo enviar solicitudes a los endpoints de la API de administración de Atlas en diferentes estados, consulta el esquema de versionado.
Agregue la cabecera de versionado Accept a las solicitudes.
Para usar la API de administración de Atlas versionada, debes proporcionar una versión de recurso para tus recursos. La primera versión es la misma en todos los recursos y para la migración inicial de la API heredada sin versión a la API con versión, debes usar el número de versión que corresponde a la fecha de la versión del recurso.
Ejemplo
El siguiente comando curl es un ejemplo de una solicitud a un endpoint de una API de administración de Atlas versionada (v2) con el encabezado:
curl --header "Authorization: Bearer {ACCESS-TOKEN}" \ --header "Accept: application/vnd.atlas.{yyyy-mm-dd}+json" \ --request {GET|DELETE} "https://cloud.mongodb.com/api/atlas/v2/{RESOURCE}/{ENDPOINT}?{PARAMS}"
También debe especificar el tipo de contenido para las solicitudes POST, PUT o PATCH. El valor del tipo de contenido puede ser uno de los siguientes:
application/jsonapplication/vnd.atlas.{yyyy-mm-dd}+json
Ejemplo
El siguiente comando de curl es un ejemplo de solicitud a un endpoint de la API de Administración de Atlas versionada (v2) con el encabezado y el tipo de contenido:
curl --header "Authorization: Bearer {ACCESS-TOKEN}" \ --header "Content-Type: application/vnd.atlas.{yyyy-mm-dd}+json" \ --header "Accept: application/vnd.atlas.{yyyy-mm-dd}+json" \ --request {POST|PUT|PATCH} "https://cloud.mongodb.com/api/atlas/v2/{RESOURCE}/{ENDPOINT}?{PARAMS}"
Para obtener más información sobre los encabezados de la API de administración de Atlas con versiones, consulte API ciclo de vida en Esquema de versionado.
Revise el registro de cambios para determinar los cambios de sintaxis para el endpoint de la API de administración de Atlas en la nueva versión del recurso.
Las nuevas versiones de los recursos de los endpoints API podrían incluir cambios disruptivos. Asegúrate de que tu solicitud al nuevo recurso incorpore esos cambios y de que el encabezado de la solicitud incluya el estado del endpoint al que estás enviando la solicitud.
Nota
No es necesario comprobar el registro de cambios de la API para la migración inicial de la Atlas Administration API no versionada a la Atlas Administration API versionada en la versión del recurso 2023-02-01 a menos que se esté migrando el recurso /v1.0/clusters a la Atlas Administration API versionada (v2) recurso /clusters. La versión inicial de la API de administración de Atlas versionada en 2023-02-01 contiene cambios de sintaxis únicamente para el recurso /clusters. Para obtener más información, consulte la especificación de la API para Clústeres.
(Opcional) Migrar el recurso Clusters de la API de administración de Atlas no versionada v1.0 al recurso Clusters de la API de administración de Atlas versionada (v2).
La versión 2023-02-01 de la API versionada de administración de Atlas contiene los siguientes cambios de sintaxis para el recurso clústeres:
Tipo de solicitud de punto final de la API de administración de Atlas versionada (v2) | Registro de cambios |
|---|---|
publicación | Incluye los siguientes cambios:
|
GET (todos) | Incluye los siguientes cambios:
|
GET (uno) | Incluye los siguientes cambios:
|
PATCH (uno) | Incluye los siguientes cambios:
|
Si utiliza el recurso de /clusters sin versión de la API de administración de Atlas para crear uno, obtener uno, obtener todos, modificar uno o borrar uno clúster, migre a los puntos de :oas-bump-atlas-op:, :oas-bump-atlas-op:, :oas-bump-atlas-op:, :oas-bump-atlas-op: y :oas-bump-atlas-op: en la API de administración de Atlas con versión (v2) Clusters.
Si aún no deseas migrar a la versión 2023-02-01, realiza solo los pasos 1 y 2 en el procedimiento para utilizar la versión 2023-01-01 API. Tenga en cuenta que 2023-01-01 está obsoleto.