Docs Menu
Docs Home
/
MongoDB Atlas
/
Programmatic Access
/
Atlas Administration API

Migrate to the New Versioned Atlas Administration API

On this page

  • Versioned Atlas Administration API Introduction
  • Versioned Atlas Administration API Lifecycle
  • Procedure

With the introduction of the Versioned Atlas Administration API (referred to here as /v2), we recommend that you migrate from the Legacy Atlas Administration API (referred to as /v1) to the new Versioned Atlas Administration API (/v2).

Versioned Atlas Administration API Introduction

The new versioned Atlas Administration API gives a significantly better overall experience in accessing Atlas programmatically. The versioned Atlas Administration API provides a predictable and consistent experience with API changes and gives better visibility into new features and changes.

Versioned Atlas Administration API Lifecycle

Atlas exposes a new resource version of an existing API endpoint when Atlas introduces breaking changes to the current stable version of the API endpoint. When Atlas exposes a new resource version, Atlas automatically deprecates the old resource version. Atlas automatically deletes the deprecated resource version twelve months after deprecation. Although Atlas will continue to support the older resource version for use in your production environment for up to twelve months, you should migrate to the new version of the API endpoint ASAP. To learn more, see the example in Versioning Schema.

Note that with resource-level versioning, each resource in the versioned Atlas Administration API might introduce a new version independently from other resources. You have to take action only when the resources you are utilizing are deprecated.

Example

Suppose Atlas introduces new /serverless resource in 2023-06-01, but /backup doesn't have any breaking changes and stays on 2023-02-01. You must migrate to 2023-06-01 only if you are utilizing the /serverless resource. If you haven't implemented the /serverless resource, you don't need to take any action.

Atlas supports deprecated resource version for at least twelve months until it is removed, which provides you with time to plan and transition to the new version. You can see changes in each new resource in the API Changelog and details of the API version in the API specification.

Procedure

To migrate to the new Versioned Atlas Administration API, you must do the following:

1

Specify the number representing the Versioned API in the base URL for the resource.

Base URL
https://cloud.mongodb.com/api/atlas/<version-number>/

Example

Consider the following base URL for the legacy version of an Atlas Administration API resource:

https://cloud.mongodb.com/api/atlas/v1.0/

With the introduction of Versioned Admin API, the preceding base URL indicates you are using resources that are not versioned. To send a request to the Versioned Atlas Administration API (/v2) resource, you must send your request to the following base URL:

https://cloud.mongodb.com/api/atlas/v2/

To learn about submitting requests to Atlas Administration API endpoints in different states, see Versioning Schema.

2

Add the versioning Accept header to requests.

To use the versioned Atlas Administration API, you must provide a resource version for your resources. The first version is the same across all resources and for the initial migration from the unversioned legacy API to the versioned API, you must use the version number that corresponds to the resource version date.

Example

The following curl command is an example of a request to a versioned Atlas Administration API (v2) endpoint with the header:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
  --header "Accept: application/vnd.atlas.{yyyy-mm-dd}+json" \
  --request {GET|DELETE}
  "https://cloud.mongodb.com/api/atlas/v2/{RESOURCE}/{ENDPOINT}?{PARAMS}"

You must specify the content type also for POST, PUT, or PATCH requests. Value for content type can be one of the following:

  • application/json

  • application/vnd.atlas.{yyyy-mm-dd}+json

Example

The following curl command is an example of a request to a versioned Atlas Administration API (v2) endpoint with the header and content type:

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
  --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}"

To learn more about versioned Atlas Administration API headers, see API lifecycle under Versioning Schema.

3

Review the changelog to determine the syntax changes for the Atlas Administration API endpoint in the new resource version.

New resource versions of API endpoints might include breaking changes. Ensure that your request to the new resource incorporates those changes and the request header includes the state of the endpoint to which you are sending the request.

Note

You need not check the API Changelog for the initial migration from the unversioned Atlas Administration API to the versioned Atlas Administration API on the resource version 2023-02-01 unless you are migrating the /v1.0/clusters resource to the versioned Atlas Administration API (v2) /clusters resource. The initial release of the versioned Atlas Administration API on 2023-02-01 contains syntax changes for only the /clusters resource. To learn more, see API specification for Clusters.

4

(Optional) Migrate the unversioned Atlas Administration API v1.0 Clusters resource to the versioned Atlas Administration API (v2) Clusters resource.

The 2023-02-01 release of the versioned Atlas Administration API contains the following syntax changes for the Clusters resource:

Versioned Atlas Administration API (v2) endpoint Request Type
Changelog

POST

Includes the following changes:

  • Removes the following request properties:

    • mongoURIWithOptions

    • providerBackupEnabled

    • mongoURIUpdated

    • srvAddress

    • replicationSpec

    • mongoURI

    • numShards

    • autoScaling

    • providerSettings

    • replicationFactor

    • replicationSpecs.regionsConfig

  • Adds the request property replicationSpecs.regionConfigs

  • Removes the following optional properties from the response:

    • mongoURIWithOptions

    • providerBackupEnabled

    • mongoURIUpdated

    • srvAddress

    • replicationSpec

    • mongoURI

    • numShards

    • autoScaling

    • providerSettings

    • replicationFactor

    • replicationSpecs.regionsConfig

  • Adds the response property replicationSpecs.regionConfigs

GET (all)

Includes the following changes:

  • Removes the following optional properties from the response:

    • results.items.mongoURIWithOptions

    • results.items.providerBackupEnabled

    • results.items.mongoURIUpdated

    • results.items.srvAddress

    • results.items.replicationSpec

    • results.items.mongoURI

    • results.items.numShards

    • results.items.autoScaling

    • results.items.providerSettings

    • results.items.replicationFactor

    • results.items.replicationSpecs.regionsConfig

  • Adds the response property results.items.replicationSpecs.regionConfigs

GET (one)

Includes the following changes:

  • Removes the following optional properties from the response:

    • mongoURIWithOptions

    • providerBackupEnabled

    • mongoURIUpdated

    • srvAddress

    • replicationSpec

    • mongoURI

    • numShards

    • autoScaling

    • providerSettings

    • replicationFactor

    • replicationSpecs.regionsConfig

  • Adds the response property results.items.replicationSpecs.regionConfigs

PATCH (one)

Includes the following changes:

  • Removes the following optional properties from the response:

    • mongoURIWithOptions

    • providerBackupEnabled

    • mongoURIUpdated

    • srvAddress

    • replicationSpec

    • mongoURI

    • numShards

    • autoScaling

    • providerSettings

    • replicationFactor

    • replicationSpecs.regionsConfig

  • Adds the response property results.items.replicationSpecs.regionConfigs

  • Removes the following optional properties from the response:

    • mongoURIWithOptions

    • providerBackupEnabled

    • mongoURIUpdated

    • srvAddress

    • replicationSpec

    • mongoURI

    • numShards

    • autoScaling

    • providerSettings

    • replicationFactor

    • replicationSpecs.regionsConfig

  • Adds the response property replicationSpecs.regionConfigs

If you use the unversioned Atlas Administration API /clusters resource to create one, get one, get all, modify one, or delete one cluster, migrate to the create one, get one, get all, modify one, and delete one endpoints in the versioned Atlas Administration API (v2) Clusters resource.

If you don't want to migrate to the 2023-02-01 version yet, perform only steps 1 and 2 in the procedure to use the 2023-01-01 API version. Note that 2023-01-01 is deprecated.

Back

Versioning Overview

Next

API Upgrades