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

snooty.toml

@@ -27,6 +27,7 @@ toc_landing_pages = [
 [constants]
 aagent = "Automation Agent"
 adf = "Atlas Data Federation"
+atlas-admin-api = "Atlas Administration API"
 atlas-cli = "Atlas CLI"
 atlas-cli-full = "MongoDB Atlas CLI"
 atlas-cli-version = "1.35.0"

source/command/atlas-api.txt

@@ -0,0 +1,154 @@
+.. _atlas-api:
+
+=========
+atlas api
+=========
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :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>``.
+
+This experimental feature streamlines script development by letting you interact 
+directly with any {+atlas-admin-api+} endpoint using the {+atlas-cli+}.
+
+To learn more about working with the {+atlas-admin-api+}, see :ref:`atlas-admin-api-access`.
+
+Syntax
+------
+
+.. code-block::
+   :caption: Command Syntax
+
+   atlas api <tag> <operationId> [options]
+
+Arguments  
+---------  
+
+* **<tag>**
+
+  *Type:* string
+
+  *Required*
+
+  The category of {+atlas-admin-api+} operations. To find the tag, check 
+  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``.
+
+* **<operationId>**
+
+  *Type:* string
+
+  *Required*
+
+  The identifier of the {+atlas-admin-api+} endpoint. 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 
+  ``https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Clusters/operation/listClusters``, 
+  the operationId is ``listClusters``.
+
+Options  
+-------  
+
+Pass in the path and query parameters for the {+atlas-admin-api+} endpoint 
+as flags. For example, if the endpoint is ``/api/atlas/v2/orgs/{orgId}/invoices/{invoiceId}``, 
+the {+atlas-cli+} command is:
+
+.. code-block:: shell
+
+   atlas api <tag> <operationId> --orgId <ORG_ID> --invoiceId <INVOICE_ID> 
+
+If applicable to the endpoint, pass in the request body using the ``--file`` option 
+or standard input (``stdin``). 
+For example:
+
+.. code-block:: shell
+
+   atlas api clusters create --file cluster-config.json
+
+In addition, the following options are available for all {+atlas-admin-api+} endpoints.
+
+.. list-table::  
+   :header-rows: 1  
+   :widths: 20 10 10 60  
+
+   * - Name  
+     - Type  
+     - Required  
+     - Description  
+   * - ``--api-version``  
+     - string  
+     - false  
+     - Specify the :ref:`version <api-versioning-overview>` of the {+atlas-admin-api+} 
+       for the command. Defaults to the latest API version.  
+   * - ``--format``  
+     - string  
+     - false  
+     - Output format. Supported formats include ``json``, ``csv``, or a Go template. 
+       Defaults to ``json``.  
+   * - ``--file``  
+     - string  
+     - false  
+     - File path to the request body content, if required by the operation. 
+       Alternatively, provide input through standard input (``stdin``).  
+   * - ``-o, --out``  
+     - string  
+     - false  
+     - File path to save the output. By default, the result is displayed in the terminal.  
+   * - ``-h, --help``  
+     - boolean  
+     - false  
+     - Help for the current command.  
+
+Inherited Options  
+-----------------  
+
+.. list-table::  
+   :header-rows: 1  
+   :widths: 20 10 10 60  
+
+   * - Name  
+     - Type  
+     - Required  
+     - Description  
+   * - ``-P, --profile``  
+     - string  
+     - false  
+     - 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>`__.  
+
+Output  
+------  
+
+If the command succeeds, the {+atlas-cli+} outputs the result of the {+atlas-admin-api+} 
+operation, formatted as specified by the ``--format`` option. If no format is provided, 
+the output defaults to JSON. For example responses, see the `{+atlas-admin-api+} Specification <https://mongodb.com/docs/atlas/reference/api-resources-spec>`__. 
+
+Examples  
+--------  
+
+.. code-block::  
+   :copyable: false  
+
+   # Create a new cluster using the latest API version:  
+   atlas api clusters createCluster --file createCluster.json  
+
+   # List all clusters for a specific organization:  
+   atlas api clusters listClusters --orgId <ORG_ID>  
+
+   # Get details of a specific invoice by organization ID and invoice ID:  
+   atlas api orgs getInvoice --orgId <ORG_ID> --invoiceId <INVOICE_ID>  
+
+   # Output in CSV format and save the result to a file:  
+   atlas api clusters listClusters --format csv --out clusters.csv  
+
+   # Specify a particular API version for an operation:  
+   atlas api clusters getCluster --name <CLUSTER_NAME> --api-version 2023-10-01  
+

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>
    auditing </command/atlas-auditing>
    auth </command/atlas-auth>
    backups </command/atlas-backups>