Skip to content

Commit f53e6b4

Browse files
erabil-mdberabil-mdb
authored
(DOCSP-46656) Adds handwritten command for atlas api. (#838)
* (DOCSP-46656) Adds handwritten command for atlas api. * Revises per tech + copy reviews. * Revises per tech + copy reviews. * Fixes table formatting.
1 parent b5133f3 commit f53e6b4

File tree

3 files changed

+181
-0
lines changed

3 files changed

+181
-0
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ toc_landing_pages = [
2727
[constants]
2828
aagent = "Automation Agent"
2929
adf = "Atlas Data Federation"
30+
atlas-admin-api = "Atlas Administration API"
3031
atlas-cli = "Atlas CLI"
3132
atlas-cli-full = "MongoDB Atlas CLI"
3233
atlas-cli-version = "1.35.0"

‎source/command/atlas-api.txt

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
.. _atlas-api:
2+
3+
=========
4+
atlas api
5+
=========
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Access all features of the `{+atlas-admin-api+} <https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/>`__
16+
by using the {+atlas-cli+} with the syntax: ``atlas api <tag> <operationId>``.
17+
18+
This experimental feature streamlines script development by letting you interact
19+
directly with any {+atlas-admin-api+} endpoint by using the {+atlas-cli+}.
20+
21+
To learn more about working with the {+atlas-admin-api+}, see :ref:`atlas-admin-api-access`.
22+
23+
Syntax
24+
------
25+
26+
.. code-block::
27+
:caption: Command Syntax
28+
29+
atlas api <tag> <operationId> [options]
30+
31+
.. important::
32+
33+
Both ``<tag>`` and ``<operationId>`` must be in :wikipedia:`camelCase <Camel_case>`.
34+
35+
Arguments
36+
---------
37+
38+
.. list-table::
39+
:header-rows: 1
40+
:widths: 30 30 10 30
41+
42+
* - Name
43+
- Type
44+
- Required
45+
- Description
46+
* - <tag>
47+
- string
48+
- true
49+
- The category of {+atlas-admin-api+} operations in :wikipedia:`camelCase <Camel_case>`.
50+
To find and format the tag, check
51+
the `API documentation <https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/>`__
52+
|url| for the endpoint. It appears after ``#tag/``, but you need to change to camelCase.
53+
54+
For example, in
55+
``https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Monitoring-and-Logs``,
56+
the tag is ``Monitoring-and-Logs``. In camelCase, it's ``monitoringAndLogs``.
57+
* - <operationId>
58+
- string
59+
- true
60+
- The identifier of the {+atlas-admin-api+} endpoint in :wikipedia:`camelCase <Camel_case>`.
61+
To find the operationId, check the
62+
`API documentation <https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/>`__
63+
|url| for the endpoint. It appears after ``operation/``.
64+
65+
For example, in
66+
``https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Clusters/operation/listClusters``,
67+
the operationId is ``listClusters``.
68+
69+
70+
Options
71+
-------
72+
73+
Pass in the path and query parameters for the {+atlas-admin-api+} endpoint
74+
as flags. For example, if the endpoint is ``/api/atlas/v2/orgs/{orgId}/invoices/{invoiceId}``,
75+
the {+atlas-cli+} command is:
76+
77+
.. code-block:: shell
78+
79+
atlas api <tag> <operationId> --orgId <ORG_ID> --invoiceId <INVOICE_ID>
80+
81+
.. note::
82+
83+
You usually don't need to specify ``--orgId`` and ``--projectId`` as they are sourced
84+
from your profile. Specify them only if they are not set in your profile.
85+
86+
If applicable to the endpoint, pass in the request body using the ``--file`` option
87+
or standard input (``stdin``).
88+
For example:
89+
90+
.. code-block:: shell
91+
92+
atlas api clusters create --file cluster-config.json
93+
94+
In addition, the following options are available for all {+atlas-admin-api+} endpoints.
95+
96+
.. list-table::
97+
:header-rows: 1
98+
:widths: 20 10 10 60
99+
100+
* - Name
101+
- Type
102+
- Required
103+
- Description
104+
* - ``--api-version``
105+
- string
106+
- false
107+
- Specify the :ref:`version <api-versioning-overview>` of the {+atlas-admin-api+}
108+
for the command. Defaults to the latest API version or the value you've configured for ``api_version`` in your profile.
109+
* - ``--format``
110+
- string
111+
- false
112+
- Output format. The default is ``json``, but the supported formats can vary by endpoint:
113+
114+
- Most endpoints output ``json``. When ``json`` is supported, you can also use a Go template.
115+
- Some endpoints support ``json`` and ``csv``, allowing you to use ``json``, ``csv``, or a Go template.
116+
- Certain endpoints output binary data (for example, logs in gzip format), requiring the ``--out`` option.
117+
118+
To determine the supported formats for an endpoint:
119+
120+
- Check the content response type examples in the `API documentation <https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/>`__.
121+
- Run ``atlas api <tag> <operationId> --help`` for details.
122+
* - ``--file``
123+
- string
124+
- false
125+
- File path to the request body content, if required by the operation.
126+
Alternatively, provide input through standard input (``stdin``).
127+
* - ``-o, --out``
128+
- string
129+
- false
130+
- File path to save the output. By default, the result is displayed in the terminal.
131+
* - ``-h, --help``
132+
- boolean
133+
- false
134+
- Help for the current command.
135+
136+
Inherited Options
137+
-----------------
138+
139+
.. list-table::
140+
:header-rows: 1
141+
:widths: 20 10 10 60
142+
143+
* - Name
144+
- Type
145+
- Required
146+
- Description
147+
* - ``-P, --profile``
148+
- string
149+
- false
150+
- Name of the profile to use from your configuration file. For more information about profiles, see `Atlas CLI Configuration <https://dochub.mongodb.org/core/atlas-cli-save-connection-settings>`__.
151+
152+
Output
153+
------
154+
155+
If the command succeeds, the {+atlas-cli+} outputs the result of the {+atlas-admin-api+}
156+
operation, formatted as specified by the ``--format`` option. If no format is provided,
157+
the output defaults to JSON. For example responses, see the `{+atlas-admin-api+} Specification <https://mongodb.com/docs/atlas/reference/api-resources-spec>`__.
158+
159+
Examples
160+
--------
161+
162+
.. code-block::
163+
:copyable: false
164+
165+
# Create a new cluster using the latest API version:
166+
atlas api clusters createCluster --file createCluster.json
167+
168+
# List all clusters for a specific organization:
169+
atlas api clusters listClusters --orgId <ORG_ID>
170+
171+
# Get details of a specific invoice by organization ID and invoice ID:
172+
atlas api orgs getInvoice --orgId <ORG_ID> --invoiceId <INVOICE_ID>
173+
174+
# Output in CSV format and save the result to a file:
175+
atlas api clusters listClusters --format csv --out clusters.csv
176+
177+
# Specify a particular API version for an operation:
178+
atlas api clusters getCluster --name <CLUSTER_NAME> --api-version 2023-10-01
179+

‎source/command/atlas.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,7 @@ Related Commands
9393
accessLists </command/atlas-accessLists>
9494
accessLogs </command/atlas-accessLogs>
9595
alerts </command/atlas-alerts>
96+
api </command/atlas-api>
9697
auditing </command/atlas-auditing>
9798
auth </command/atlas-auth>
9899
backups </command/atlas-backups>

0 commit comments

Comments
 (0)