Versioned Atlas Administration API Overview
Atlas provides versioned Atlas Administration API for a predictable and consistent experience when handling API changes. The API versioning happens at the individual API resource-level. So, you need to take action if and when Atlas deprecates the resources that you are utilizing. You don't need to take any action if you haven't implemented a resource for which Atlas released a new version. This allows you to plan for new features, prevent breaking changes, and ensure a smooth integration process while maintaining stability and minimizing disruptions in your production environment.
Benefits of the Versioned Atlas Administration API
The new versioned Atlas Administration API gives a significantly better overall experience in accessing Atlas programmatically. The versioned Atlas Administration API provides the following:
Clear Separation of Breaking and Non-Breaking Changes
Atlas introduces all new feature with breaking changes in a new resource version. Features that contain non-breaking changes will continue to be added to the current, stable resource version. When Atlas introduces a new resource version, you can continue to use the current stable resource version until it is fully deprecated while you develop and test on the new API resource version.
Extended Support and Deprecation Periods
Atlas deprecates and then removes resource versions only when it introduces a new stable API resource version. Atlas will continue to support the older resource version for use in your production environment for up to twelve months, which provides you with time to plan and execute your migration to the next version.
Versioning Schema
Starting with the new Versioned Atlas Administration API (v2), Atlas Administration API version is based on the lifecycle of the Atlas Administration API resource.
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.
Important
The stages only apply to Atlas Administration API endpoints in Versioned
Atlas Administration API (v2) of the resource. These stages don't
affect Atlas Administration API endpoints in resource v1.0 or
v1.5. Atlas exposes all legacy (v1.0 and v1.5)
Atlas Administration API resources in its first release on 2023-02-01 in
stable state.
stableAtlas 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. Atlas exposes all legacy (v1.0 and v1.5) Atlas Administration API resources in its first release on
2023-02-01in stable state. Atlas will support the first release (2023-01-01 and 2023-02-01) of the versioned Atlas Administration API for 24 months after its deprecation. Note that the/clustersresource version 2023-01-01 (and equivalent of/v1.0/clusters) resource is marked as deprecated with two years deprecation window.To use Atlas Administration APIs in this state, send a request to the resource and include the following as the HTTP Accept header:
Accept: application/vnd.atlas.<yyyy-mm-dd>+json where the value for
<yyyy-mm-dd>is the release date of the endpoint as listed in the documentation and the changelog.Atlas returns 406 Not Acceptable error response code if your request omits or specifies a resource version that doesn't exist in the header.
deprecatedAtlas 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.
Example
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 You can continue to send requests to older resource versions of the endpoint until they are removed. However, you should migrate to the latest resource version as soon as possible to mitigate disruptions when older resource versions are removed. To learn more about migrating to a new resource version, see Migrate to the New Versioned Atlas Administration API.
sunsetAtlas 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.
Example
The following example illustrates the lifecycle of a resource and its impact on versioning.
The preceding illustration shows the following:
Release Date | Release Details | API Lifecyle |
|---|---|---|
2023-06-01 | First release of a resource in the Versioned API.
It has a deprecation period of 12 months. |
|
2024-06-01 | New resource version created, older versions are automatically
deprecated. |
|
2025-01-01 | New stable version created, with short sunset |
|
API Endpoints
For legacy unversioned Atlas Administration API endpoints, Atlas
introduced new and breaking changes in the same version. Starting in
versioned Atlas Administration API (v2), Atlas introduces breaking
changes only in a new resurce version. Atlas will continue to
introduce non-breaking changes to existing stable version. Use the
release date of a resource to submit a request to a specific version of
a versioned Atlas Administration API (v2) endpoint.
The following table shows the legacy API endpoint versions, whether
the version has a corresponding versioned Atlas Administration API (v2)
endpoint, and the release date of the versioned Atlas Administration API
(v2) resource. Note that an equivalent of v1.0 in the unversioned
Atlas Administration API is represented by 2023-01-01 in the versioned
Atlas Administration API, which is now deprecated.
Version Number | Supported in v2? | v2 Resource Version (in yyyy-mm-dd format) |
|---|---|---|
v1.0 | √ | 2023-01-01 |
v1.5 | √ | 2023-02-01 |
Next Steps
Review the API changelog, which gives you visibility into all API changes across different versions.
Review the API Specification, which contains information for all stable and deprecated resource versions.
Follow the steps in the Migration Guide to migrate from the current unversioned Atlas Administration API to the new versioned Atlas Administration API.