Skip to content

Commit ae35a3e

Browse files
kanchana-mongodberabil-mdb
kanchana-mongodb
and
erabil-mdb
authored
DOCSP-48672 Document API Access (#982)
* DOCSP-48672 Document API Access * Apply suggestions from code review Co-authored-by: Evelyn Rabil <[email protected]> * DOCSP-48672 small copy updates * DOCSP-48672 updates for JV's feedback * DOCSP-48672 added banner --------- Co-authored-by: Evelyn Rabil <[email protected]>
1 parent 9a3075f commit ae35a3e

File tree

3 files changed

+195
-0
lines changed

3 files changed

+195
-0
lines changed

‎snooty.toml

Lines changed: 8 additions & 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.41.2"
@@ -123,3 +124,10 @@ value = """\
123124
**Data Lake is deprecated.** \
124125
As of September 2024, Data Lake is deprecated and will reach end-of-life. It will be removed on September 30, 2025. If you use Data Lake, you should migrate to alternative solutions before the service is removed. To learn more, see :adl:`Migration Guide </data-lake-deprecation/>`\
125126
"""
127+
128+
[[banners]]
129+
targets = ["atlas-cli-admin-api.txt"]
130+
variant = "warning"
131+
value = """\
132+
{+atlas-cli+} support for running commands with the {+atlas-admin-api+} is in Preview. The feature and the corresponding documentation might change at any time during the Preview period. You can provide feedback on this feature through the `MongoDB Feedback Engine for Atlas CLI <https://feedback.mongodb.com/forums/930808-atlas-cli>`__.\
133+
"""

‎source/atlas-cli-admin-api.txt

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
.. _atlas-cli-admin-api:
2+
3+
===============================================================
4+
Run {+atlas-cli+} Commands with the {+atlas-admin-api+}
5+
===============================================================
6+
7+
.. meta::
8+
:description: Learn to execute Atlas CLI commands using the Atlas Administration API.
9+
10+
.. default-domain:: mongodb
11+
12+
.. contents:: On this page
13+
:local:
14+
:backlinks: none
15+
:depth: 1
16+
:class: singlecol
17+
18+
This tutorial shows you how to run {+atlas-cli+} commands with the
19+
{+atlas-admin-api+}. You can use every {+atlas-admin-api+} resource
20+
and endpoint from the {+atlas-cli+} to create and manage |service|
21+
deployments. {+atlas-cli+} support for the {+atlas-admin-api+} provides the
22+
following benefits:
23+
24+
- Full feature parity with the {+atlas-admin-api+}.
25+
- Quicker access to new {+atlas-admin-api+} resources and endpoints.
26+
- A unified, predictable command structure for automation.
27+
- Ability to pin a desired API version, ensuring your scripts remain
28+
reliable, even if you update the CLI.
29+
30+
Syntax
31+
------
32+
33+
To use {+atlas-cli+} with the {+atlas-admin-api+}, run the command in
34+
the following format:
35+
36+
.. code-block:: shell
37+
38+
atlas api <tag> <operationId> [options]|--file <fileName>.json --version <api-resource-version>
39+
40+
Arguments
41+
~~~~~~~~~
42+
43+
.. list-table::
44+
:widths: 20 10 70
45+
:header-rows: 1
46+
47+
* - Argument
48+
- Necessity
49+
- Description
50+
51+
* - ``<tag>``
52+
- Required
53+
- The name of the tag used in the {+atlas-admin-api+} documentation
54+
|url| for the |api| resource. The tag is hyphen-separated in the
55+
{+atlas-admin-api+} documentation |url|. However, you must
56+
convert it to camelcase in the {+atlas-cli+} command syntax.
57+
58+
For example, consider the following |url| for an
59+
{+atlas-admin-api+} resource:
60+
61+
.. code-block:: shell
62+
63+
https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Example-Tag-Name/
64+
65+
For accessing the resource in the preceding |url|, replace
66+
``<tag>`` with ``exampleTagName`` in the command syntax:
67+
68+
.. code-block:: shell
69+
70+
atlas api exampleTagName <operationId>
71+
72+
For more examples, see :ref:`atlas-cli-admin-api-examples`.
73+
74+
* - ``<operationId>``
75+
- Required
76+
- The identifier of the operation in the {+atlas-admin-api+}
77+
documentation |url| for the |api| endpoint. The value is in
78+
camelcase format.
79+
80+
For example, consider the following |url| for an
81+
{+atlas-admin-api+} endpoint operation:
82+
83+
.. code-block:: shell
84+
85+
https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Example-Tag-Name/operation/exampleEndpointOperationId
86+
87+
For performing the operation supported by the endpoint in the
88+
preceding |url|, replace ``<tag>`` with ``exampleTagName`` and use
89+
the ID of the operation, ``exampleEndpointOperationId``, as shown the
90+
command.
91+
92+
.. code-block:: shell
93+
94+
atlas api exampleTagName exampleEndpointOperationId [options]
95+
96+
For more examples, see :ref:`atlas-cli-admin-api-examples`.
97+
98+
Options
99+
~~~~~~~
100+
101+
You can pass the |api| path, query, and request body parameters as
102+
options with the command. You can specify the options directly
103+
with the command or using a |json| file. The command also supports the
104+
following options:
105+
106+
.. list-table::
107+
:widths: 20 10 70
108+
:header-rows: 1
109+
110+
* - Option
111+
- Necessity
112+
- Description
113+
114+
* - ``--file``
115+
- Conditional
116+
- |json| file that contains the |api| path, query, and request body
117+
parameters for the operation. This is required only if there are
118+
required path, query, or request body parameters for the
119+
operation that you aren't specifying directly with the command.
120+
121+
* - ``--version``
122+
- Optional
123+
- |api| resource version to use. We recommend using it to pin your
124+
scripts to specific |api| versions. If omitted, the command
125+
defaults to the latest version (or your profile's configured
126+
version). However, we recommend explicitly setting the version to
127+
ensure your scripts remain stable. This protects your scripts
128+
from breaking when new |api| versions are released with
129+
potentially incompatible changes.
130+
131+
.. _atlas-cli-admin-api-examples:
132+
133+
Examples
134+
--------
135+
136+
The following {+atlas-cli+} command with the {+atlas-admin-api+}
137+
demonstrates how to retrieve a compressed (``.gz``) log file that
138+
contains a range of log messages for the specified host for the
139+
specified project:
140+
141+
.. code-block:: shell
142+
143+
atlas api monitoringAndLogs getHostLogs --groupId 5e2211c17a3e5a48f5497de3 --hostName mycluster-shard-00-02.7hgjn.mongodb.net --logName mongodb --output gzip --version 2025-03-12
144+
145+
The following {+atlas-cli+} command with the {+atlas-admin-api+}
146+
demonstrates how to create a cluster by using the ``--file`` option.
147+
148+
.. code-block:: shell
149+
150+
atlas api clusters createCluster --groupId 5e2211c17a3e5a48f5497de3 --file cluster-config.json --version 2025-03-12
151+
152+
To learn more about creating a configuration file for a cluster, see
153+
:ref:`atlas-cli-cluster-config-file`.
154+
155+
The following {+atlas-cli+} command with the {+atlas-admin-api+}
156+
demonstrates how to simulate regional cloud provider outages.
157+
This simulation lets you test your application's failover behavior and
158+
disaster recovery procedures in a controlled environment separate from
159+
production. The command uses a file named ``outage_simulation.json``
160+
with the following settings:
161+
162+
.. code-block::
163+
164+
{
165+
"outageFilters": [
166+
{
167+
"cloudProvider": "AWS",
168+
"regionName": "US_EAST_1",
169+
"type": "REGION"
170+
}
171+
]
172+
}
173+
174+
.. io-code-block::
175+
:copyable: true
176+
177+
.. input::
178+
:language: shell
179+
180+
atlas api clusterOutageSimulation startOutageSimulation --groupId 5e2211c17a3e5a48f5497de3 --clusterName myCluster --file outage_simulation.json --version 2025-03-12
181+
182+
.. output::
183+
:language: shell
184+
185+
{"clusterName":"myCluster","groupId":"5e2211c17a3e5a48f5497de3","id":"6808ed9bed0b0b51caee336b","outageFilters":[{"cloudProvider":"AWS","regionName":"US_EAST_1","type":"REGION"}],"startRequestDate":"2025-04-23T13:39:39Z","state":"START_REQUESTED"}
186+

‎source/atlas-cli-tutorials.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,4 +62,5 @@ You can also go straight to the :ref:`{+atlas-cli+} Commands
6262
Local & Cloud Deployments </atlas-cli-local-cloud>
6363
Test Automations </atlas-cli-ephemeral-cluster>
6464
Run Commands with Docker </atlas-cli-docker>
65+
Run Commands with the Atlas Administration API </atlas-cli-admin-api>
6566

0 commit comments

Comments
 (0)