CLOUDP-325300: [AtlasCLI] Support preview and upcoming stability levels for L1 commands #3984

jeroenvervaeke · 2025-06-18T16:26:48Z

Proposed changes

Introduced stability levels to the CLI versions, use api.Version instead of a plain string
Update the atlas api layers to support upcoming and preview (private/public) stability levels
- Updated CLI layer
  - Show warning that the API is unstable to user when preview version is selected
- Updated execution layer
  - Ensured that the upcoming/preview headers are set correctly
  - Added additional unit tests
Update docs tool
- Commands with only one private preview version don't get their own documentation page (In line with product description)

Testing

Extended snapshot tests
Extended existing unit tests

Manual tests

I included the getOpenApiInfo operation manually for testing and then ran the commands below.
The operation got reverted afterwards.

Stable

❯ ./bin/atlas api openApi getOpenApiInfo --debug --version 2024-08-05

GET /api/atlas/v2/openapi/info HTTP/1.1
Host: cloud-qa.mongodb.com
User-Agent: Go-http-client/1.1
Accept: application/vnd.atlas.2024-08-05+json
Accept-Encoding: gzip



HTTP/1.1 200 OK
Content-Length: 339
Content-Type: application/vnd.atlas.2024-08-05+json
Date: Wed, 18 Jun 2025 11:55:11 GMT
Server: mdbws
X-Envoy-Upstream-Service-Time: 35

{"info":{"title":"MongoDB Atlas Administration API.","description":"License information of the MongoDB Atlas Administration API.","termOfService":"https://www.mongodb.com/mongodb-management-service-terms-and-conditions","license":{"name":"CC BY-NC-SA 3.0 US","url":"https://creativecommons.org/licenses/by-nc-sa/3.0/us/"},"version":"2.0"}}
{"info":{"title":"MongoDB Atlas Administration API.","description":"License information of the MongoDB Atlas Administration API.","termOfService":"https://www.mongodb.com/mongodb-management-service-terms-and-conditions","license":{"name":"CC BY-NC-SA 3.0 US","url":"https://creativecommons.org/licenses/by-nc-sa/3.0/us/"},"version":"2.0"}}

Preview

Note that the CLI is requesting preview but the server is responding with upcoming, this is normal server behavior because the preview version is deprecated.

❯ ./bin/atlas api openApi getOpenApiInfo --debug --version preview    
warning: you've selected a public preview version of the endpoint, this version is subject to breaking changes.

GET /api/atlas/v2/openapi/info HTTP/1.1
Host: cloud-qa.mongodb.com
User-Agent: Go-http-client/1.1
Accept: application/vnd.atlas.preview+json
Accept-Encoding: gzip



HTTP/1.1 200 OK
Content-Length: 339
Content-Type: application/vnd.atlas.2025-09-22.upcoming+json
Date: Wed, 18 Jun 2025 11:56:24 GMT
Deprecation: Mon, 22 Sep 2025 00:00:00 GMT
Server: mdbws
Sunset: Wed, 22 Oct 2025 00:00:00 GMT
X-Envoy-Upstream-Service-Time: 32

{"info":{"title":"MongoDB Atlas Administration API.","description":"License information of the MongoDB Atlas Administration API.","termOfService":"https://www.mongodb.com/mongodb-management-service-terms-and-conditions","license":{"name":"CC BY-NC-SA 3.0 US","url":"https://creativecommons.org/licenses/by-nc-sa/3.0/us/"},"version":"2.0"}}
{"info":{"title":"MongoDB Atlas Administration API.","description":"License information of the MongoDB Atlas Administration API.","termOfService":"https://www.mongodb.com/mongodb-management-service-terms-and-conditions","license":{"name":"CC BY-NC-SA 3.0 US","url":"https://creativecommons.org/licenses/by-nc-sa/3.0/us/"},"version":"2.0"}}

Upcoming

Server responded with an error, which is ok.
The CLI set the headers correctly.

❯ ./bin/atlas api openApi getOpenApiInfo --debug --version 2025-09-22.upcoming

GET /api/atlas/v2/openapi/info HTTP/1.1
Host: cloud-qa.mongodb.com
User-Agent: Go-http-client/1.1
Accept: application/vnd.atlas.2025-09-22.upcoming+json
Accept-Encoding: gzip



HTTP/1.1 406 Not Acceptable
Content-Length: 140
Content-Type: application/json
Date: Wed, 18 Jun 2025 11:57:15 GMT
Server: mdbws
X-Envoy-Upstream-Service-Time: 53

{"error":406,"reason":"Not Acceptable","detail":"Invalid accept header or version date.","errorCode":"INVALID_VERSION_DATE","parameters":[]}

…ming and preview

…en executing a preview version

andreaangiolillo

LGTM, comments are not a blocker

andreaangiolillo · 2025-06-19T08:12:08Z

internal/cli/api/api.go

+	// If the version is valid, check if it's supported
+	if err == nil {
+		for _, commandVersion := range apiCommand.Versions {
+			if commandVersion.Version.Equal(version) {
+				return
+			}
 		}
+		return


I think you want to return the error if the ParseVersion failed or at least log the error to stderr to help debugging.

Suggested change

// If the version is valid, check if it's supported

if err == nil {

for _, commandVersion := range apiCommand.Versions {

if commandVersion.Version.Equal(version) {

return

}

}

return

// If the version is valid, check if it's supported

if err != nil {

return err

}

for _, commandVersion := range apiCommand.Versions {

if commandVersion.Version.Equal(version) {

return

}

}

return

Line 466 covers this message.

Example:

❯ ./bin/atlas api clusters listClusters --version not-valid warning: version 'not-valid' is not supported for this endpoint, using default API version '2024-08-05'; consider pinning a version to ensure consisentcy when updating the CLI {"links":[{"href":"https://cloud-qa.mongodb.com/api/atlas/v2/groups/67d048784f073c51c7d330a4/clusters?pageNum=1&itemsPerPage=100","rel":"self"}],"results":[],"totalCount":0}

andreaangiolillo · 2025-06-19T08:16:35Z

internal/cli/api/api.go

+	if err != nil {
+		return
+	}


Similar to the above comment, we should at least log the error to stderror in case the impossible happen and we need to debug the issue. If you don't agree, you could then remove this if and have version, _ := shared_api.ParseVersion(*versionString)

Thanks for the suggestion, I've updated these branches with an error message!

andreaangiolillo · 2025-06-19T08:18:23Z

internal/cli/api/api.go

+	if commandVersion.PublicPreview {
+		fmt.Fprintf(os.Stderr, "warning: you've selected a public preview version of the endpoint, this version is subject to breaking changes.\n")
+	} else {
+		fmt.Fprintf(os.Stderr, "warning: you've selected a private preview version of the endpoint, this version might not be available for your account and is subject to breaking changes.\n")
+	}


Super clear messages 👍

andreaangiolillo · 2025-06-19T08:19:46Z

tools/cmd/api-generator/convert_commands.go

+// ```yaml
+// x-xgen-preview:
+//
+//	name: charts-dashboards


name is set only for private preview since all the public preview API are in the same file.

Good catch, removed the name from the example yaml

…String, to match Stringer interface

github-actions · 2025-06-19T12:09:49Z

Coverage Report 📈

Branch	Commit	Coverage
master	`bed65ce`	25.2%
CLOUDP-325300	`e5e4ae8`	25.7%
	Difference	.5%

andreaangiolillo

LGTM

jeroenvervaeke added 5 commits June 17, 2025 15:37

Introduce stability levels structs

11b7d8b

Improved TestConvertToHttpRequest test to cover preview and upcoming

2201deb

Moved privatepreview to CommandVersion, Added snapshot tests for upco…

60e3cca

…ming and preview

Fixed public preview logic, private by default. Also print warning wh…

e77e74e

…en executing a preview version

Don't create docs for commands with only private preview versions

85ff603

jeroenvervaeke requested a review from a team as a code owner June 18, 2025 16:26

github-actions bot added the atlascli label Jun 18, 2025

Added copyright notice

a986e33

andreaangiolillo previously approved these changes Jun 19, 2025

View reviewed changes

jeroenvervaeke marked this pull request as draft June 19, 2025 09:08

jeroenvervaeke added 2 commits June 19, 2025 11:19

Improved version sorting, added more unit tests. Renamed ToString -> …

b8410ea

…String, to match Stringer interface

ran make gen-api-commands

f548b63

jeroenvervaeke dismissed andreaangiolillo’s stale review via f548b63 June 19, 2025 10:28

jeroenvervaeke added 6 commits June 19, 2025 11:57

Fix version date sorting, implement stringer

c2f3a20

Ran make addcopy

a68c3c8

fixed bug when the CLI is called with an unsupported version

e99332d

Added error print for cases where we received an invalid version

ef62972

improve error message

a0b091e

removed 'name' from public preview example

e5e4ae8

mongodb deleted a comment from github-actions bot Jun 19, 2025

jeroenvervaeke marked this pull request as ready for review June 19, 2025 12:35

andreaangiolillo approved these changes Jun 19, 2025

View reviewed changes

jeroenvervaeke merged commit 94057bb into master Jun 19, 2025
22 of 24 checks passed

jeroenvervaeke deleted the CLOUDP-325300 branch June 19, 2025 12:39

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

CLOUDP-325300: [AtlasCLI] Support preview and upcoming stability levels for L1 commands #3984

CLOUDP-325300: [AtlasCLI] Support preview and upcoming stability levels for L1 commands #3984

Uh oh!

jeroenvervaeke commented Jun 18, 2025

Uh oh!

andreaangiolillo left a comment

Uh oh!

andreaangiolillo Jun 19, 2025

Uh oh!

jeroenvervaeke Jun 19, 2025

Uh oh!

andreaangiolillo Jun 19, 2025

Uh oh!

jeroenvervaeke Jun 19, 2025

Uh oh!

andreaangiolillo Jun 19, 2025

Uh oh!

andreaangiolillo Jun 19, 2025

Uh oh!

jeroenvervaeke Jun 19, 2025

Uh oh!

github-actions bot commented Jun 19, 2025

Uh oh!

andreaangiolillo left a comment

Uh oh!

Uh oh!

Uh oh!

CLOUDP-325300: [AtlasCLI] Support preview and upcoming stability levels for L1 commands #3984

CLOUDP-325300: [AtlasCLI] Support preview and upcoming stability levels for L1 commands #3984

Uh oh!

Conversation

jeroenvervaeke commented Jun 18, 2025

Proposed changes

Testing

Manual tests

Stable

Preview

Upcoming

Uh oh!

andreaangiolillo left a comment

Choose a reason for hiding this comment

Uh oh!

andreaangiolillo Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

jeroenvervaeke Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

andreaangiolillo Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

jeroenvervaeke Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

andreaangiolillo Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

andreaangiolillo Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

jeroenvervaeke Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jun 19, 2025

Uh oh!

andreaangiolillo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!