From 312e431fa809243f58f9de72b7dee7125b1b85ab Mon Sep 17 00:00:00 2001 From: Evelyn Rabil Date: Wed, 22 Jan 2025 09:20:31 -0700 Subject: [PATCH 1/4] (DOCSP-46656) Adds handwritten command for atlas api. --- snooty.toml | 1 + source/command/atlas-api.txt | 154 +++++++++++++++++++++++++++++++++++ source/command/atlas.txt | 1 + 3 files changed, 156 insertions(+) create mode 100644 source/command/atlas-api.txt 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..4609d115 --- /dev/null +++ b/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+} `__ +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 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] + +Arguments +--------- + +* **** + + *Type:* string + + *Required* + + The category of {+atlas-admin-api+} operations. To find the tag, check + the `API documentation `__ + |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``. + +* **** + + *Type:* string + + *Required* + + The identifier of the {+atlas-admin-api+} endpoint. 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 + +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. + * - ``--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 `__. + +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 From d15ffcb384f50db6eaad3f7a4c6158259881bf2f Mon Sep 17 00:00:00 2001 From: Evelyn Rabil Date: Fri, 24 Jan 2025 12:19:11 -0700 Subject: [PATCH 2/4] Revises per tech + copy reviews. --- source/command/atlas-api.txt | 75 +++++++++++++++++++++++------------- 1 file changed, 48 insertions(+), 27 deletions(-) diff --git a/source/command/atlas-api.txt b/source/command/atlas-api.txt index 4609d115..9fca1a0d 100644 --- a/source/command/atlas-api.txt +++ b/source/command/atlas-api.txt @@ -13,10 +13,10 @@ atlas api :class: singlecol Access all features of the `{+atlas-admin-api+} `__ -using the {+atlas-cli+} with the syntax: ``atlas 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 using the {+atlas-cli+}. +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`. @@ -28,32 +28,41 @@ Syntax atlas api [options] +.. important:: + + Both ```` and ```` must be in :wikipedia:`camelCase `. + Arguments --------- -* **** - - *Type:* string - - *Required* - - The category of {+atlas-admin-api+} operations. To find the tag, check - the `API documentation `__ - |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``. +.. list-table:: + :header-rows: 1 + :widths: 20 10 10 60 + + * - 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``. -* **** - - *Type:* string - - *Required* - - The identifier of the {+atlas-admin-api+} endpoint. 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 ------- @@ -66,6 +75,11 @@ the {+atlas-cli+} command is: 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: @@ -88,12 +102,19 @@ In addition, the following options are available for all {+atlas-admin-api+} end - string - false - Specify the :ref:`version ` of the {+atlas-admin-api+} - for the command. Defaults to the latest API version. + 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. Supported formats include ``json``, ``csv``, or a Go template. - Defaults to ``json``. + - 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 From 09c2191e87ab2916e47dde93e5e3a29df53d9beb Mon Sep 17 00:00:00 2001 From: Evelyn Rabil Date: Fri, 24 Jan 2025 12:22:41 -0700 Subject: [PATCH 3/4] Revises per tech + copy reviews. --- source/command/atlas-api.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/command/atlas-api.txt b/source/command/atlas-api.txt index 9fca1a0d..74442d1b 100644 --- a/source/command/atlas-api.txt +++ b/source/command/atlas-api.txt @@ -37,7 +37,7 @@ Arguments .. list-table:: :header-rows: 1 - :widths: 20 10 10 60 + :widths: 20 20 10 50 * - Name - Type @@ -113,7 +113,8 @@ In addition, the following options are available for all {+atlas-admin-api+} end - 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. + + - Check the content response type examples in the `API documentation `__. - Run ``atlas api --help`` for details. * - ``--file`` - string From 20c38a5584544cfdb8156af1144a72455722a505 Mon Sep 17 00:00:00 2001 From: Evelyn Rabil Date: Mon, 27 Jan 2025 09:08:12 -0700 Subject: [PATCH 4/4] Fixes table formatting. --- source/command/atlas-api.txt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/source/command/atlas-api.txt b/source/command/atlas-api.txt index 74442d1b..935065fb 100644 --- a/source/command/atlas-api.txt +++ b/source/command/atlas-api.txt @@ -37,7 +37,7 @@ Arguments .. list-table:: :header-rows: 1 - :widths: 20 20 10 50 + :widths: 30 30 10 30 * - Name - Type @@ -50,6 +50,7 @@ Arguments 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``. @@ -59,7 +60,9 @@ Arguments - 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 + |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``.