Student

Luke Sanderson

Software Engineering Intern

MongoDB's [Atlas Administration API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/) is a great way to perform administrative tasks for Atlas programmatically. The Administration API can be used to manage your Atlas organizations, projects, deployments and more. This allows you to automate and integrate your administrative tasks into your own systems.

To explore the MongoDB Atlas Administration API, you can use the [public MongoDB Administration API workspace](https://www.postman.com/mongodb-devrel/workspace/mongodb-atlas-administration-apis/overview) provided by the MongoDB Developer Relations team. In this article, we will show you how to create and manage a cluster in MongoDB Atlas using the MongoDB Administration API and Postman.

## Getting started

To complete this tutorial, you will need a [Postman account](https://identity.getpostman.com/signup). Postman also [recommends installing the desktop app](https://learning.postman.com/docs/getting-started/basics/about-postman-agent/) to avoid issues with sending requests from the web browser. You will need to set up your Altas cluster and fork the Postman collection to start using it. The following sections provide some more detailed instructions on how to achieve this if you need them.

### Set up your MongoDB Atlas account

The first step is to set up a MongoDB Atlas account. If you don't have an account already, you can [get one for free](https://www.mongodb.com/cloud/atlas/register). For this tutorial, an API key with the `Organization Owner` role is required. Follow the instructions from the [documentation](https://www.mongodb.com/docs/atlas/configure-api-access/#grant-programmatic-access-to-an-organization) for detailed directions on granting programmatic access. Make sure you keep track of the public API key and private API key as these will be used later.

![Image of the MongoDB Atlas logo][2]


### Fork the Postman collection

From the [public MongoDB Administration API workspace](https://www.postman.com/mongodb-devrel/workspace/mongodb-atlas-administration-apis/overview) on Postman, you will find many Postman collections, one for each [version of the API](https://www.mongodb.com/docs/atlas/api/versioned-api-overview/). The most recent version, which appears at the bottom of the list, is the one we are interested in. Click on the three dots next to the collection name and select Create a fork from the popup menu.

Then, follow the instructions on-screen to add this collection to your private workspace. Make sure to also select the MongoDB Atlas Administration API environment in the Environments to fork drop-down.

![Screenshot of menu for creating a fork of the Postman Collection. The MongoDB Atlas Administration API Environment has been selected to also fork.][3]

### Configure your environment

You will now need to configure the Postman environment that you just forked. Start by opening the Environments tab on the left-hand side. Next, find the MongoDB Atlas Administration API environment.

Here, you find a table of variables, namely `digestAuthUsername` and `digestAuthPassword`. These will hold the initial values of `{{vault:mongodb-public-api-key}}` and  `{{vault:mongodb-private-api-key}}`. These point to secrets in the Postman vault, which you need to create.

To create these secrets, click the Vault button in the bottom right of the screen or use the control + shift + v shortcut. Create two fields named `mongodb-public-api-key` and `mongodb-private-api-key` and enter the public and private keys you created earlier. The value of secrets stored in the Postman vault are stored locally and are encrypted using Advanced Encryption Standard (AES) with a 256-bit key length.

> If you're using the Postman web app to send requests with references to vault secrets, you must use the [Postman Desktop Agent](https://learning.postman.com/docs/getting-started/basics/about-postman-agent/#postman-desktop-agent) or the [Postman Browser Agent](https://learning.postman.com/docs/getting-started/basics/about-postman-agent/#postman-browser-agent). By default, the requests will return a 401 unauthorized response. We recommend using the Postman desktop app to avoid issues related to the web app and its many [Postman Agents](https://learning.postman.com/docs/getting-started/basics/about-postman-agent/). 

Finally, select MongoDB Atlas Administration API as the active environment from the environment drop-down.

![Screenshot of the Postman Vault screen. Two secrets have been added called 'public-api-key' and 'private-api-key'. The user is also selecting the MongoDB Atlas Administration API Environment as the active environment.][4]

## Using the Atlas Administration API

Now you are ready to use the Atlas Administration API, navigate back to the forked collection by selecting the Collection tab on the left-hand side.

### Checking your connection

To start, use the search bar to find the request called "Return the status of this MongoDB application." Click on the GET request with that name, which will show the options for sending the request.

To send this request, simply click Send. The authorization parameters will be automatically filled from the vault by using the active environment. This should result in a response that displays the public API key that was used as well as the roles it has. The response body should look similar to below:

```
{
    "apiKey": {
        "accessList": [],
        "id": "36b340b5857d214ba750f9f1",
        "publicKey": "bnamtsop",
        "roles": [
            {
                "orgId": "6a94e205a9936e310d07bed3",
                "roleName": "ORG_OWNER"
            }
        ]
    },
    "appName": "MongoDB Atlas",
    "build": "b1d222c3c2c606eb64a7c0da856824b708a40fbb",
    "links": [
        {
            "href": "https://cloud.mongodb.com/api/atlas/v2",
            "rel": "self"
        },
        {
            "href": "https://cloud.mongodb.com/api/atlas/v2/orgs/6a94e205a9936e310d07bed3/apiKeys/36b340b5857d214ba750f9f1",
            "rel": "https://cloud.mongodb.com/apiKeys"
        }
    ],
    "throttling": false
}
```

If the request fails or the API key does not have the `ORG_OWNER` role, then retry the previous steps.

Copy the `orgId` from this response as this will be used in the next request.

One great feature of Postman is the ability to generate code snippets for any given request. By clicking the `</>` icon on the right-hand side of the screen, you can generate a code snippet for the "Return the status of this MongoDB application" request in cURL. Clicking on the drop-down initially labelled cURL gives you the option to generate code for most major programming languages.

### Create a project

Now that we know all the variables have been set correctly and we know the organization ID, let's create a project. Search for the request named "Create One Project."

This is a POST request and requires a body to describe the project we are creating. Navigate to the Body tab and paste the following body into the text box, replacing `<orgID>` with the organization ID copied from the previous response.

```
{
  "name": "Postman Project",
  "orgId": "<orgID>"
}
```

Now, send this request. This should result in the creation of a new project and a response body similar to below:

```
{
    "clusterCount": 0,
    "created": "2024-08-08T16:06:12Z",
    "id": "63b4acfac067b91e203b1e11",
    "links": [...],
    "name": "Postman Project",
    "orgId": "6a94e205a9936e310d07bed3"
}
```

Copy the value of the "id" field as this is your project/group ID. As you can see from the `clusterCount` field, there are currently no clusters in this project so let's create one.

### Create a cluster

Navigate to the request named "Create One Cluster from One Project" via the search function. This POST request uses both path variables under the Params tab as well as a body under the Body tab.

In the Params tab, set the `:groupId` variable to the ID copied from the previous response body. This is used to select the project the operation is under.

In the Body tab, paste the following body into the text box.

```
{
    "name": "MyFreeCluster",
    "clusterType": "REPLICASET",
    "replicationSpecs": [
        {
            "regionConfigs": [
                {
                    "electableSpecs": {
                        "diskIOPS": 0,
                        "ebsVolumeType": "STANDARD",
                        "instanceSize": "M0",
                        "nodeCount": 1
                    },
                    "priority": 7,
                    "providerName": "TENANT",
                    "backingProviderName":"AWS",
                    "regionName": "US_EAST_1"
                }
            ]
        }
    ]
}
```

This states the configuration options for an `M0` cluster. `M0` clusters are free forever and suitable for users learning MongoDB or developing small proof-of-concept applications.

Click Send to create the cluster.

To view a more detailed description of this endpoint as well as a detailed explanation of the request body schema, click the Documentation icon and follow the link to the documentation page for each endpoint.

![Screenshot of the 'Create One Cluster from One Project' request page. The user is currently on the body tab and has entered a body that describes a free M0 cluster. The user also has the documentation tab open on the right side.][5]

### Load a sample dataset

Navigate to the request named "Load Sample Dataset Request into Cluster" via the search function. This POST request only uses path variables under the Params tab.

Enter the same groupId from previous steps. For the name field, enter "MyFreeCluster" or the name of the cluster that was just created if you chose a different name.

Click Send to load the sample dataset. This should result in a response body such as:

```
{
    "_id": "63b4acfac067b91e203b1e11",
    "clusterName": "MyFreeCluster",
    "completeDate": null,
    "createDate": "2024-08-09T09:46:03Z",
    "errorMessage": null,
    "state": "WORKING"
}
```

As you can see, the state is set to `WORKING`. To check if the dataset has finished being loaded, navigate to the "Check Status of Cluster Sample Dataset Request" request page.

On the params page, enter your groupId. The sampleDatasetId value is the value of `_id` in the previous response body.

Sending this GET request will give you an update on the progress of the dataset loading. Once the dataset has been loaded, the response body will look similar to the following:

```
{
    "_id": "63b4acfac067b91e203b1e11",
    "clusterName": "MyFreeCluster",
    "completeDate": "2024-08-09T09:47:19Z",
    "createDate": "2024-08-09T09:46:03Z",
    "errorMessage": null,
    "state": "COMPLETED"
}
```

### Retrieve metrics about your cluster

Now that we have set up a cluster and loaded some sample data, let's retrieve some metrics about the cluster during that operation.

First, to retrieve the measurements, we need the IDs of the MongoDB processes in the cluster. To do this, navigate to the "Return All MongoDB Processes in One Project" request.

Enter the groupId and click Send. This will result in a response containing information about all the processes in the project --- in this case, just one cluster.

```
{
    "links": [ ... ],
    "results": [
        { ...
        },
        {
            "created": "2024-08-09T09:22:31Z",
            "groupId": "63b4acfac067b91e203b1e11",
            "hostname": "atlas-aaaaaa-shard-00-01.xpgisai.mongodb.net",
            "id": "atlas-aaaaaa-shard-00-01.xpgisai.mongodb.net:27017",
            "lastPing": "2024-08-09T11:00:33Z",
            "links": [ ... ],
            "port": 27017,
            "replicaSetName": "atlas-aaaaaa-shard-0",
            "typeName": "REPLICA_PRIMARY",
            "userAlias": "bb-bbbbbbb-shard-00-01.xpgisai.mongodb.net",
            "version": "7.0.12"
        },
        { ...
         }
    ],
    "totalCount": 3
}
```

We are interested in the process with the `typeName` field being equal to `REPLICA_PRIMARY` as this is the primary node of this cluster. Copy the `id` of this process as this will be used in the next request.

Finally, navigate to the request called "Return Measurements for One MongoDB Process." This is a GET request with many path and query parameters. You may wish to look at [the documentation](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Monitoring-and-Logs/operation/getHostMeasurements) for a full explanation of each of these parameters but for our request, we only require the following query parameters. Click on the Params tab to see those parameters.

-   m --- List of types of measurements to request. Set this field to "CONNECTIONS."
-   period --- Duration in the [ISO 8601 duration format](https://en.wikipedia.org/wiki/ISO_8601#Durations) over which Atlas reports the metrics. Set this field to "PT1H."
-   granularity --- Duration that specifies the interval at which Atlas reports the metrics. Set this field to "PT1M."

Make sure these three query parameters are enabled with the checkbox and all others are disabled. This query requests the number of connections over each minute for the past hour.

Next, set the path variables. Set the `id` copied from the previous request body to the field named ProcessId. The groupId field should be set to the same value as the previous requests.

Sending this GET request should result in a response with a body similar to the following:

```
{
    "end": "2024-08-09T11:24:06Z",
    "granularity": "PT1M",
    "groupId": "63b4acfac067b91e203b1e11",
    "hostId": "atlas-aaaaaa-shard-00-01.xpgisai.mongodb.net:27017",
    "links": [ ... ],
    "measurements": [
        {
            "dataPoints": [
                {
                    "timestamp": "2024-08-09T09:25:33Z",
                    "value": 0
                },
               ... ,
                {
                    "timestamp": "2024-08-09T10:01:33Z",
                    "value": 11
                },
                ... ,
                {
                    "timestamp": "2024-08-09T10:10:16Z",
                    "value": 0
                },
             ],
            "name": "CONNECTIONS",
            "units": "SCALAR"
        }
    ],
    "processId": "atlas-aaaaaa-shard-00-01.xpgisai.mongodb.net:27017",
    "start": "2024-08-09T09:25:33Z"
}
```

These data points can be plotted to show the number of connections over time. To learn in more detail about the different metrics this endpoint can provide, click on the Documentation icon and follow the link to the [documentation for the Atlas Administration API](https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Monitoring-and-Logs/operation/getHostMeasurements).

## Summary

And just like that, we created a project, deployed a cluster, and requested metrics about the cluster all through the Atlas Administration API using Postman. If you want to learn more about using the Atlas Administration API programmatically, a great place to start is [Calling the MongoDB Atlas Administration API: How to Do it From Node, Python, and Ruby](https://www.mongodb.com/developer/products/atlas/nodejs-python-ruby-atlas-api/).


  [1]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt47717bd905e61bf6/66c3770f45395da133bb6bb6/MongoDB_Atlas_Logo.png
  [2]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt09613f146d9e9b4e/66c384322f80d2d180f36a6b/MongoDB_Atlas_Logo_(1).png
  [3]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt81e5528835ef7f3d/66c3773588b74e8566b14854/Postman_create_a_fork_screenshot.png
  [4]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt51acdab5e2732438/66c3777100844a1bf1b0283f/Postman_Vault_with_environment_screenshot.png
  [5]: https://images.contentstack.io/v3/assets/blt39790b633ee0d5a7/blt22679f5875200ffd/66c377e4316653030e4a1152/Postman_documentation_tab_screenshot.png

To explore the MongoDB Atlas Administration API, you can use the public MongoDB Administration API workspace provided by the MongoDB Developer Relations team. In this article, we will show you how to create and manage a cluster in MongoDB Atlas using the MongoDB Administration API and Postman.


Luke Sanderson

Content by Luke Sanderson

Configuring Atlas in Postman With the Atlas Administration API