Con la introducción de la API de administración de atlas versionados (referida aquí como /v2), le recomendamos que migre de la API de administración de Atlas heredada (conocida como /v1) a la nueva API de administración de Atlas con versiones (/v2).
Introducción a la API de administración de Atlas versionada
La nueva versión de la API de Administración de Atlas ofrece una experiencia general significativamente mejorada al acceder a Atlas mediante programación. Esta API proporciona una experiencia predecible y consistente con los cambios de la API y ofrece una mejor visibilidad de las nuevas funciones y cambios.
Ciclo de vida de la API de administración de Atlas versionada
Atlas expone una nueva versión de recursos de una existente API endpoint cuando Atlas introduce cambios disruptivos en la versión estable actual del API endpoint. Cuando Atlas expone una nueva versión del recurso, Atlas descontinúa automáticamente la antigua versión del recurso. Atlas elimina automáticamente la versión obsoleta del recurso doce meses después de la obsolescencia. Aunque Atlas seguirá admitiendo la versión anterior del recurso para su uso en tu entorno de producción hasta por doce meses, debes migrar lo antes posible a la nueva versión del API endpoint ASAP. Para obtener más información, consulta el ejemplo en Esquema de versiones.
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 un nuevo recurso en 2023-06-01, pero /backup no presenta cambios importantes y permanece en 2023-02-01. Debe migrar a 2023-06-01 solo si utiliza ese recurso. Si no ha implementado el recurso, no necesita 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 de Atlas con versiones, debe hacer lo siguiente:
Especifique el número que representa la API versionada en la URL base del recurso.
https://cloud.mongodb.com/api/atlas/<version-number>/
Ejemplo
Considere el siguiente URL base para la versión heredada de un recurso de la API de administración de Atlas:
https://cloud.mongodb.com/api/atlas/v1.0/
Con la introducción de la API de administrador versionada, el URL 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 de Atlas Versionado (/v2), se debe enviar la 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 el Accept encabezado de versión 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 aprender más sobre los encabezados versionados de la Administración API de Atlas, ve ciclo de vida de la API en Esquema de versionado.
Revise el registro de cambios para determinar los cambios de sintaxis para el punto final de la API de administración de Atlas en la nueva versión del recurso.
Las nuevas versiones del recurso de los endpoints de API pueden 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 necesitas consultar el Registro de Cambios de la API para la migración inicial de la API de Administración de Atlas sin versión a la API de Administración de Atlas con versión en la versión de recurso 2023-02-01 a menos que estés migrando el recurso /v1.0/clusters a la API de Administración de Atlas con versión (v2) /clusters recurso. La primera versión de la API de administración de Atlas en 2023-02-01 contiene cambios de sintaxis únicamente para el recurso /clusters. Para obtener más información, consulta la especificación de la API para Clusters.
(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:
|
PARCHE (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 sólo los pasos 1 y 2 del procedimiento para utilizar la versión de la API 2023-01-01. Ten en cuenta que 2023-01-01 está obsoleto.