> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Versioned Atlas Administration API Overview

Atlas provides a versioned Atlas Administration API for a predictable and consistent experience when handling API (Application Programming Interface) changes. The API (Application Programming Interface) versioning happens at the individual API (Application Programming Interface) 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 features with breaking changes in a new resource version. The current, stable resource version still includes features that contain non-breaking changes. 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 (Application Programming Interface) resource version.

### Extended Support and Deprecation Periods

Atlas deprecates and then removes resource versions only when it introduces a new stable API (Application Programming Interface) resource version. Atlas continues 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 `preview`, `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.

Atlas supports endpoints in this state for evaluation, testing, and development purposes only. Don't use Atlas Administration API endpoints in preview in your production environment as endpoints in preview might include breaking and non-breaking changes. Atlas Administration API endpoints in preview also have a short deprecation window of approximately 30 days or shorter, after which the endpoints could move to either `stable` or `deprecated` state.

To use API (Application Programming Interface) endpoints in preview, send a request to the resource and include the following HTTP header:

```shell
Accept: application/vnd.atlas.preview+json
```

Atlas supports stable endpoints for use in production environments. Atlas provides documentation, with [changelogs](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog.md#std-label-versioned-api-changelog), for all stable endpoints. A resource version in this state only updates 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-01` in stable state. Atlas supports 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 `/clusters` resource 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:

```shell
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.](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog.md#std-label-versioned-api-changelog)

Atlas returns [406 Not Acceptable](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/406) error response code if your request omits or specifies a resource version that doesn't exist in the header.

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 supports 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.

```shell
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 avoid 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.](https://www.mongodb.com/docs/atlas/api/migrate-to-new-version.md#std-label-atlas-migrate-api-version)

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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410) error response code.

### Illustrated API Resource Lifecycle

The following example illustrates the lifecycle of a resource and its impact on versioning.

![Illustration of admin API versioning lifecycle for a specific API resource.](/images/admin-api-versioning-strategy-2.png)

The preceding illustration shows the following:

| **Release Date** | **Release Details** | **API Lifecycle** |
| --- | --- | --- |
| 2024-01-01 | A new stable version is released. | `#stable`: `application/vnd.atlas.2024-01-01+json` |
| 2025-01-01 | A new stable version is released.; The `2024-01-01` version is deprecated. | `#deprecated`: `application/vnd.atlas.2024-01-01+json`; `#stable`: `application/vnd.atlas.2025-01-01+json` |
| 2026-01-01 | The `2024-01-01` version is sunset.; A new preview version is introduced, and then deprecated within the year. | `#sunset`: `application/vnd.atlas.2024-01-01+json`; `#stable`: `application/vnd.atlas.2025-01-01+json`; `#preview`: `application/vnd.atlas.preview+json` |
| 2027-01-01 | A new stable version is released.; The `2025-01-01` version is deprecated.; The preview version is sunset. | `#sunset`: `application/vnd.atlas.2024-01-01+json`; `#deprecated`: `application/vnd.atlas.2025-01-01+json`; `#sunset`: `application/vnd.atlas.preview+json`; `#stable`: `application/vnd.atlas.2027-01-01+json` |
| 2028-01-01 | A new stable version is released.; The `2025-01-01` version is sunset. | `#sunset`:`application/vnd.atlas.2024-01-01+json`; `application/vnd.atlas.2025-01-01+json`; `application/vnd.atlas.preview+json`; `#stable`: `application/vnd.atlas.2027-01-01+json` |

### API (Application Programming Interface) 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 resource version. Atlas continues 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 (Application Programming Interface) 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

1. Review the [API changelog](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog.md#std-label-versioned-api-changelog), which gives you visibility into all API (Application Programming Interface) changes across different versions.

2. Review the [API Specification](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/), which contains information for all stable and deprecated resource versions.

3. Follow the steps in the [Migration Guide](https://www.mongodb.com/docs/atlas/api/migrate-to-new-version.md#std-label-atlas-migrate-api-version) to migrate from the current unversioned Atlas Administration API to the new versioned Atlas Administration API.