MongoDB API V2?

The new version 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.

It is not needed to check the API Changelog for the initial migration unless you are using the /cluster resource as it contains the only syntax changes from v1.0 to the initial release of v2 for 2023-02-01.

Steps to migrate to the New Versioned Atlas Administration API

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

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/

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, the date for the first release is 2023-02-01.

The following curl command is an example of a GET or DELETE request to 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}"

The following curl command is an example of a POST, PUT or PATCH request to 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}"

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.

Versioned Atlas Administration API Lifecycle

Starting in Versioned Atlas Administration API (v2), Atlas Administration API endpoints go through the stable, deprecated, and sunset stages in the lifecycle.

stable

Atlas supports stable endpoints for use in production environments. Atlas provides documentation, with changelogs, for all stable endpoints. Resource version in this state will only be updated with non-breaking changes.

When Atlas introduces breaking changes to endpoints, it creates a new resource version. When a new resource version is released, Atlas also automatically deprecates the current stable version of that resource.

deprecated

Atlas automatically deprecates a resource version when Atlas introduces a new, stable resource version. Atlas releases a new, stable version when it introduces breaking changes to an existing resource.

Atlas notifies you about deprecated resource versions in the response header for requests. Atlas will support the first releases of the Atlas Administration API (2023-01-01 and 2023-02-01) for twenty-four months after deprecation. Subsequently, Atlas supports any future deprecated resource versions for use in your production environment for twelve months before automatically removing them.

The following shows an example response header for a request to a deprecated resource scheduled for removal in the future.

Deprecation: Wed, 1 Feb 2023 00:00:00 GMT
Sunset: Sun, 1 Jun 2025 00:00:00 GMT

sunset

Atlas automatically removes resource versions after one year of deprecation. If you send a request to a removed resource version, Atlas returns the 410 Gone error response code.

Contact us to schedule your consultation.

Delbridge is a privately held global company with offices in Canada, the USA, Costa Rica, and Romania.

Delbridge Solutions specializes in providing Corporate Performance Management, Sales Performance Management, and Data & Software Engineering.

888.866.6176

 info@delbridge.solutions

Join the Delbridge Community!