diff --git a/snooty.toml b/snooty.toml index b869ff0f..17fd9746 100644 --- a/snooty.toml +++ b/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" diff --git a/source/command/atlas-api.txt b/source/command/atlas-api.txt new file mode 100644 index 00000000..935065fb --- /dev/null +++ b/source/command/atlas-api.txt @@ -0,0 +1,179 @@ +.. _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+} `__ +by using the {+atlas-cli+} with the syntax: ``atlas api ``. + +This experimental feature streamlines script development by letting you interact +directly with any {+atlas-admin-api+} endpoint by 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 [options] + +.. important:: + + Both ```` and ```` must be in :wikipedia:`camelCase `. + +Arguments +--------- + +.. list-table:: + :header-rows: 1 + :widths: 30 30 10 30 + + * - Name + - Type + - Required + - Description + * - + - string + - true + - The category of {+atlas-admin-api+} operations in :wikipedia:`camelCase `. + To find and format the tag, check + the `API documentation `__ + |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``. + * - + - string + - true + - The identifier of the {+atlas-admin-api+} endpoint in :wikipedia:`camelCase `. + To find the operationId, check the + `API documentation `__ + |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 --orgId --invoiceId + +.. note:: + + You usually don't need to specify ``--orgId`` and ``--projectId`` as they are sourced + from your profile. Specify them only if they are not set in your profile. + +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 ` of the {+atlas-admin-api+} + for the command. Defaults to the latest API version or the value you've configured for ``api_version`` in your profile. + * - ``--format`` + - string + - false + - Output format. The default is ``json``, but the supported formats can vary by endpoint: + + - Most endpoints output ``json``. When ``json`` is supported, you can also use a Go template. + - Some endpoints support ``json`` and ``csv``, allowing you to use ``json``, ``csv``, or a Go template. + - Certain endpoints output binary data (for example, logs in gzip format), requiring the ``--out`` option. + + To determine the supported formats for an endpoint: + + - Check the content response type examples in the `API documentation `__. + - Run ``atlas api --help`` for details. + * - ``--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 `__. + +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 `__. + +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 + + # Get details of a specific invoice by organization ID and invoice ID: + atlas api orgs getInvoice --orgId --invoiceId + + # 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 --api-version 2023-10-01 + \ No newline at end of file diff --git a/source/command/atlas.txt b/source/command/atlas.txt index 118b6ba4..9c5db11a 100644 --- a/source/command/atlas.txt +++ b/source/command/atlas.txt @@ -93,6 +93,7 @@ Related Commands accessLists accessLogs alerts + api auditing auth backups