(DOCSP-46656) Adds handwritten command for atlas api. #838

erabil-mdb · 2025-01-22T16:21:20Z

Self-Review Checklist

Check that the submodule pulled in the right changes (if applicable).
Define taxonomy values at top of page.
Add genre facets (tutorial or reference), as in this example PR.
Add programmingLanguage (if necessary).
Add meta keywords (if necessary).
Resolve any new warnings or errors in the build.
Proofread for spelling and grammatical errors.
Check staging for rendering issues.
Confirm links are working.

netlify · 2025-01-22T16:21:52Z

✅ Deploy Preview for docs-atlas-cli ready!

Name	Link
🔨 Latest commit	`20c38a5`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-atlas-cli/deploys/6797af75f6f6fe0008049180
😎 Deploy Preview	https://deploy-preview-838--docs-atlas-cli.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

jeroenvervaeke · 2025-01-22T17:44:17Z

source/command/atlas-api.txt

+.. code-block::
+   :caption: Command Syntax
+
+   atlas api <tag> <operationId> [options]


While it's correct that we use <tag> and <operationId>, we use a camelCase version of these values.

This will mainly influence <tag>, afaik the current operationIds are already in camelCase.

Some examples:

Flex Clusters -> flexClusters

Monitoring and Logs -> monitoringAndLogs

I don't see this captured anywhere in this page yet.

jeroenvervaeke · 2025-01-22T17:45:38Z

source/command/atlas-api.txt

+  the `API documentation <https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/>`__ 
+  |url| for the endpoint. It appears after ``#tag/``. For example, in 
+  ``https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Clusters/operation/listClusters``, 
+  the tag is ``Clusters``.


Regarding my last comment about casing commands would live under atlas api clusters [operationId]

jeroenvervaeke · 2025-01-22T17:47:28Z

source/command/atlas-api.txt

+
+.. code-block:: shell
+
+   atlas api <tag> <operationId> --orgId <ORG_ID> --invoiceId <INVOICE_ID> 


It might be helpful to mention that --orgId and --projectId are not required; they'll be taken from your profile when they're not set. (Unless they're not set on the profile, then they're needed, but they should be set in most cases)

jeroenvervaeke · 2025-01-22T17:48:20Z

source/command/atlas-api.txt

+     - Type  
+     - Required  
+     - Description  
+   * - ``--api-version``  


Same here api_version can be set as a property on your profile, if that's set then this value will be used when --api-version is not provided.

jeroenvervaeke · 2025-01-22T17:50:58Z

source/command/atlas-api.txt

+   * - ``--format``  
+     - string  
+     - false  
+     - Output format. Supported formats include ``json``, ``csv``, or a Go template. 


The output format depends on the endpoint.

Most endpoints will output json, but there are some exceptions.

When an endpoint supports json, then you can provided json or a Go template as output.

When an endpoint supports json/csv you can provide all 3 options

There are also endpoints which output binary data, like logs (gzip). In that case --out becomes required.

The easiest ways to see what's supported is to:

check the content response type examples on the API docs example

run atlas api <tag> <operationId> --help

davidhou17

A few comments back to you!

davidhou17 · 2025-01-23T16:02:17Z

source/command/atlas-api.txt

+   :class: singlecol
+
+Access all features of the `{+atlas-admin-api+} <https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/>`__ 
+using the {+atlas-cli+} with the syntax: ``atlas api <tag> <operationId>``.


nit: ambiguous who is "using" the atlas-cli (could refer to the API)

Suggested change

using the {+atlas-cli+} with the syntax: ``atlas api <tag> <operationId>``.

by using the {+atlas-cli+} with the syntax: ``atlas api <tag> <operationId>``.

davidhou17 · 2025-01-23T16:02:25Z

source/command/atlas-api.txt

+using the {+atlas-cli+} with the syntax: ``atlas api <tag> <operationId>``.
+
+This experimental feature streamlines script development by letting you interact 
+directly with any {+atlas-admin-api+} endpoint using the {+atlas-cli+}.


Suggested change

directly with any {+atlas-admin-api+} endpoint using the {+atlas-cli+}.

directly with any {+atlas-admin-api+} endpoint by using the {+atlas-cli+}.

davidhou17 · 2025-01-23T16:03:51Z

source/command/atlas-api.txt

+
+   atlas api <tag> <operationId> [options]
+
+Arguments  


I think we should use a table for the arguments here, similar to other pages in the Atlas CLI docs

davidhou17

LGTM % couple nits for the table so it's easier to read!

davidhou17 · 2025-01-24T20:25:02Z

source/command/atlas-api.txt

+Arguments  
+---------  
+
+.. list-table::


nit: Can we improve the UX of this table by updating the widths and the spacing in the description?
i.e. expand name and type columns a bit longer so they don't wrap

davidhou17 · 2025-01-24T20:25:48Z

source/command/atlas-api.txt

+       |url| for the endpoint. It appears after ``#tag/``, but you need to change to camelCase. 
+       For example, in 
+       ``https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Monitoring-and-Logs``, 
+       the tag is ``Monitoring-and-Logs``. In camelCase, it's ``monitoringAndLogs``.
+   * - <operationId>
+     - string
+     - true
+     - The identifier of the {+atlas-admin-api+} endpoint in :wikipedia:`camelCase <Camel_case>`. 
+       To find the operationId, check the 
+       `API documentation <https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/>`__ 
+       |url| for the endpoint. It appears after ``operation/``. For example, in 


I think these descriptions could benefit from a space between the overview and the example to improve legibility.

Suggested change

|url| for the endpoint. It appears after ``#tag/``, but you need to change to camelCase.

For example, in

``https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Monitoring-and-Logs``,

the tag is ``Monitoring-and-Logs``. In camelCase, it's ``monitoringAndLogs``.

* - <operationId>

- string

- true

- The identifier of the {+atlas-admin-api+} endpoint in :wikipedia:`camelCase <Camel_case>`.

To find the operationId, check the

`API documentation <https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/>`__

|url| for the endpoint. It appears after ``operation/``. For example, in

|url| for the endpoint. It appears after ``#tag/``, but you need to change to camelCase.

For example, in

``https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Monitoring-and-Logs``,

the tag is ``Monitoring-and-Logs``. In camelCase, it's ``monitoringAndLogs``.

* - <operationId>

- string

- true

- The identifier of the {+atlas-admin-api+} endpoint in :wikipedia:`camelCase <Camel_case>`.

To find the operationId, check the

`API documentation <https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/>`__

|url| for the endpoint. It appears after ``operation/``.

For example, in

sarahsimpers · 2025-01-27T15:28:31Z

source/command/atlas.txt

@@ -93,6 +93,7 @@ Related Commands
   accessLists </command/atlas-accessLists>
   accessLogs </command/atlas-accessLogs>
   alerts </command/atlas-alerts>
+   api </command/atlas-api>


This page is autogenerated, so this change will be overwritten at the next release. I don't think we can have this on this page due to our automation system unless they add it upstream.

@jeroenvervaeke are you able to add this upstream? This is so the new page shows up in the left-hand table of contents.

erabil-mdb force-pushed the DOCSP-46656 branch from 97f9aba to de5686a Compare January 22, 2025 16:44

(DOCSP-46656) Adds handwritten command for atlas api.

312e431

erabil-mdb force-pushed the DOCSP-46656 branch from de5686a to 312e431 Compare January 22, 2025 16:50

jeroenvervaeke suggested changes Jan 22, 2025

View reviewed changes

davidhou17 reviewed Jan 23, 2025

View reviewed changes

erabil-mdb added 2 commits January 24, 2025 12:19

Revises per tech + copy reviews.

d15ffcb

Revises per tech + copy reviews.

09c2191

erabil-mdb force-pushed the DOCSP-46656 branch from d48c0db to 09c2191 Compare January 24, 2025 19:35

erabil-mdb requested review from davidhou17 and jeroenvervaeke January 24, 2025 19:43

davidhou17 approved these changes Jan 24, 2025

View reviewed changes

sarahsimpers reviewed Jan 27, 2025

View reviewed changes

sarahsimpers mentioned this pull request Jan 27, 2025

(DOCSP-46837) Adds an exclude to avoid overwriting handwritten atlas-api file mongodb/mongodb-atlas-cli#3576

Merged

6 tasks

Fixes table formatting.

20c38a5

jeroenvervaeke approved these changes Jan 28, 2025

View reviewed changes

erabil-mdb merged commit f53e6b4 into mongodb:master Feb 7, 2025
4 checks passed

erabil-mdb deleted the DOCSP-46656 branch February 7, 2025 18:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

(DOCSP-46656) Adds handwritten command for atlas api. #838

(DOCSP-46656) Adds handwritten command for atlas api. #838

erabil-mdb commented Jan 22, 2025 •

edited

Loading

netlify bot commented Jan 22, 2025 •

edited

Loading

jeroenvervaeke Jan 22, 2025

jeroenvervaeke Jan 22, 2025

jeroenvervaeke Jan 22, 2025

jeroenvervaeke Jan 22, 2025

jeroenvervaeke Jan 22, 2025

davidhou17 left a comment

davidhou17 Jan 23, 2025

davidhou17 Jan 23, 2025

davidhou17 Jan 23, 2025

davidhou17 left a comment

davidhou17 Jan 24, 2025

davidhou17 Jan 24, 2025 •

edited

Loading

sarahsimpers Jan 27, 2025

erabil-mdb Jan 27, 2025


		.. code-block:: shell

		atlas api <tag> <operationId> --orgId <ORG_ID> --invoiceId <INVOICE_ID>

	using the {+atlas-cli+} with the syntax: ``atlas api <tag> <operationId>``.
	by using the {+atlas-cli+} with the syntax: ``atlas api <tag> <operationId>``.

	directly with any {+atlas-admin-api+} endpoint using the {+atlas-cli+}.
	directly with any {+atlas-admin-api+} endpoint by using the {+atlas-cli+}.

(DOCSP-46656) Adds handwritten command for atlas api. #838

(DOCSP-46656) Adds handwritten command for atlas api. #838

Conversation

erabil-mdb commented Jan 22, 2025 • edited Loading

Self-Review Checklist

netlify bot commented Jan 22, 2025 • edited Loading

✅ Deploy Preview for docs-atlas-cli ready!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidhou17 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidhou17 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidhou17 Jan 24, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

erabil-mdb commented Jan 22, 2025 •

edited

Loading

netlify bot commented Jan 22, 2025 •

edited

Loading

davidhou17 Jan 24, 2025 •

edited

Loading