Improved Developer Experience with the Atlas Admin API

With MongoDB Atlas, we meet our developers where they are and offer multiple ways to get started and work with Atlas. One of the ways to get started programmatically with Atlas is through the Atlas Administration API. It provides programmatic access to Atlas resources such as clusters, database users, or backups to name a few, enabling developers to perform operational tasks like creating, modifying, and deleting resources. We are excited to announce two key capabilities that will improve the developer experience when working with the Atlas Administration API.

Versioned Atlas Administration API

If you use the Atlas Administration API today, you are working with the unversioned Administration API (/v1). We have heard your feedback on the challenges around the API changes not having a clear policy as well as communication gaps about the new features/ deprecations. To address this, we are excited to now introduce resource-level versioning with our new versioned Atlas Administration API ( /v2). Here is what you can expect:

1. More predictability and consistency in handling API changes: With this new versioning, any breaking changes that can impact your code will only be introduced in a new resource version. You can rest assured that no breaking changes will affect your production code running the current, stable version. Also, deprecation will occur with the introduction of a new stable API resource version. This will give you at least 1 year to upgrade before the removal of the deprecated resource version. It adds more predictability to what’s coming to the API.

2. Minimum impact with resource-based versioning: With the resource level versioning, whenever we talk about API versions we’re referring to the actual API resource versions represented by date. So once you migrate from the current unversioned Administration API (/v1) to the new versioned Administration API (/v2), this will point to version 2023-02-01. To make the initial migration process smooth and easy this first resource version applies to all API resources (e.g. /serverless, /backup, /clusters, etc.). However, moving forward, each resource can introduce a new version (e.g. /serverless can move to 2023-06-01, /backup can stay on 2023-02-01) independently from each other at various points in time. The advantage is that if you have not implemented the e.g. /serverless resource and say a new version is introduced, you will not need to take any action. You will only need to take action if and when the resources you are utilizing are deprecated.

3. More time to plan your migration: Once a particular resource version is deprecated, there will be enough time ( 12 months) before it is removed, so this will give you ample time to plan and transition to the new version.

4. Improved context and visibility: Our updated documentation has all the details to guide you through the versioning process. Whether it’s a release of a new endpoint, deprecation of an existing resource version, or a non-breaking change to a #stable resource - all of them are now tracked on a dedicated and automatically updated Changelog. Other than that we provide more visibility and context on any API changes through the API specification which presents information for all stable and deprecated resource versions enabling you to access documentation that’s relevant for your particular case.

We have made it very simple for you to get started with the new versioned Administration API (/v2). To start using it you need to migrate from the current Unversioned Administration API (/v1) to the new Versioned Administration API (/v2). This migration can be done smoothly by making two changes in your code:

1. Update the path of each endpoint from /v1 to /v2.

2. Add a version header to each endpoint:
   application/vnd.atlas.2023-02-01+json.

The 2023-02-01 version will have a long support timeframe of 2 years from its deprecation, giving you ample time to transition.

Go SDK for the Atlas Administration API

One of the mechanisms that simplifies interaction with APIs is the availability of SDKs. To make it easy to get started and work with the Versioned Administration API, we are excited to introduce the new Go SDK for the Administration API. If you are a Go developer and have interacted with the Atlas Administration API, you must be familiar with our current Go client. We are now introducing the new Go SDK for the Atlas Admin API. This provides a significantly improved developer experience for Go developers as it supports full endpoint coverage, improves the speed of getting started with the versioned Admin API, provides you a consistent experience when working with the Admin API, and gives you the choice of version for better control of changes and the impact on the scripts. Let’s look at some of the benefits you can expect:

• Full Atlas Administration API endpoint coverage: The new Go SDK allows you to access all the features and capabilities that the Atlas Administration API offers today with full endpoint coverage. This ensures you can programmatically leverage the full breadth of the developer data platform.

• Flexibility in choosing the API resource version: When interacting with the new versioned Atlas Administration API through the Go SDK client, you can choose a particular version of the Admin API, giving you control over when you are impacted by breaking changes or always work with the latest version.

• Ease of use: Your getting started experience for Admin API through the Go SDK client is now much more simplified with fewer lines of code since it includes pre-built functions, structs, and methods that encapsulate the complexity of HTTP requests, authentication, error handling, versioning, and other low-level details.

• Immediate access to updates: When using the new Go SDK, you can immediately access any newly released Atlas Admin API capabilities. And every time a new version of Atlas is released, the SDK will be quickly updated and continuously maintained, ensuring compatibility with any changes in the API.