Programmatic API Management of your MongoDB Atlas Database Clusters

MongoDB Atlas has a full featured API which allows our users to programmatically create, modify and delete their clusters. We'll go over some basics on how to do this using curl in our bash shell. The goal of this post is to show you how to configure API access and use the basic features available.

Pre-Requisites:

1. Access to a bash shell on your computer or a VM. (Mac or Linux is fine)
2. curl (ssl support is required)
3. MongoDB Atlas Cluster Group - Sign up at https://mongodb.com/atlas
4. Basic understanding of how to utilize APIs.

API Configuration:

First, log into your MongoDB Atlas Control Panel https://cloud.mongodb.com/user/login

Now navigate to the "Settings" section on the left menu. You'll see under "Personal Settings" a section for "Public API Access", click this and you'll then be presented with options to create an API key and then set a whitelist of IP addresses you are able to access the API from with your authenticated key.

Create the Key

First, we will generate an API key. Click the +GENERATE button at the top of the section next to "API Keys" and provide a description. I will use "test-jay.gordon" but there's no specific information required; this is for your own labeling.

Once the key is generated you'll receive a box as above with the key provided. Save this, it will not be repeated for you again. If you are using git, do not check this into to a public repository for security reasons.

Whitelist IP

In this situation, I'll just want to allow "ALL" (0.0.0.0/0) since I am using this temporarily, however if you have a specific subnet of servers that you expect to invoke these functions from, you'll want to whitelist these particular IPs.

Click the ADD+ button next to the API Whitelist section and enter any IP you would like to whitelist with the appropriate CIDR annotation. You can do this multiple times for multiple ranges or IP addresses.

Click confirm and then we will be ready to start working with our API now that we have the Key and our whitelist configured:

As you can see, we obscure the full key to ensure it is secure. Protect this resource always, if you no longer require it you may DISABLE or DELETE it by clicking the gear icon under "Actions":

Create a Cluster:

We'll now use the command prompt on our local computer to do the following tasks:

1. Create a JSON file with our configuration requirements for our cluster
2. Write a small curl http POST against the API to create the cluster
3. Write a small curl http GET against the API to view our cluster

If you review [the spec for our MongoDB Atlas Clusters API](https://docs.atlas.mongodb.com/reference/api/clusters/ "the spec for our MongoDB Atlas Clusters API') you'll see the basics of how to create a curl command for creating a cluster:

POST /api/atlas/v1.0/groups/GROUP-ID/clusters

You must include the following fields and their values when creating a new cluster:

• name
• providerSettings.instanceSizeName
• providerSettings.providerName
• providerSettings.regionName
• backupEnabled

All other editable fields are optional. If you do not specify an optional field, MongoDB Atlas uses the field’s current default value. To view the current default values used for new clusters: open the Atlas interface; click the button to add a cluster; view the default selections; close the window without saving changes.

I want to make this easy for myself for the future, so I am going to place these configuration requirements in a simple JSON formatted text file:

{
  "name" : "DataStore",
  "numShards" : 1,
  "replicationFactor" : 3,
  "providerSettings" : {
    "providerName" : "AWS",
    "regionName" : "US_EAST_1",
    "instanceSizeName" : "M30",
    "diskIOPS" : 120,
    "encryptEBSVolume" : false
  },
  "diskSizeGB" : 40,
  "backupEnabled" : true
}

As you can see I have placed the required values for the cluster's name, replication factor, shard total, name of our hosting provider, the region within AWS, the instance size, the disk size, the total amount of IOPS and backups enabled. I saved the file as "json_out.txt" for myself, but you can call it whatever you like. Now let's build our curl statement and execute it. We require two more bits of information to finalize this.

1. Your username for MongoDB Atlas
2. Your Atlas group ID. Your username is what you authenticated with when you first logged in to the MongoDB Atlas control panel. The Group ID can be found by going to "Settings" and clicking "Group Settings" on the left side of the page. At the very top, you should see a GROUP ID string:

The string above is an example of my group, so be sure to get yours! Now we can build our curl and get our cluster built. Feel free to type this in a editor or just in the bash shell.I prefer to do so in vim so I can save it and modify if I make a mistake.
Now let's look at a few parts of our curl command:

curl -i -u "jay.gordon:$APIKEY" --digest -H "Content-Type: application/json" -X POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/575ece95e4b0ec4f28db42ca/clusters" --data @json_out.txt

• curl: this is the binary that's running the command for us
• "jay.gordon:$APIKEY": here i added APIKEY as a variable as to not share it with you, but you may replace it with the key you received earlier (feel free to create a variable in bash if you'd like)
• https URI: this is the uri we are executing our API against, we've provided our group ID as to ensure we've done this against the right resource
• --data @json_out.txt: the JSON file containing the requirements for how our cluster will be built.

We're ready to execute the command, let's build our MongoDB Atlas M30 cluster named DataStore with 40 GB of disk, backups enabled, IOPS of 120 and 3 replicas in total.

bash-3.2$ curl -i -u "jay.gordon:$APIKEY" --digest -H "Content-Type: application/json" -X POST "https://cloud.mongodb.com/api/atlas/v1.0/groups/575ece95e4b0ec4f28db42ca/clusters" --data @json_out.txt

Looks like it worked! Here's our output:

HTTP/1.1 201 Created
Date: Fri, 09 Dec 2016 16:41:16 GMT
Content-Length: 506
Content-Type: application/json
{
  "backupEnabled": true,
  "diskSizeGB": 40,
  "groupId": "575ece95e4b0ec4f28db42ca",
  "links": [
    {
      "href": "https:\/\/cloud.mongodb.com\/api\/atlas\/v1.0\/groups\/575ece95e4b0ec4f28db42ca\/clusters\/DataStore",
      "rel": "self"
    }
  ],
  "mongoDBMajorVersion": "3.2",
  "mongoDBVersion": "3.2.11",
  "mongoURIUpdated": "2016-12-09T16:41:16Z",
  "name": "DataStore",
  "numShards": 1,
  "providerSettings": {
    "providerName": "AWS",
    "diskIOPS": 120,
    "encryptEBSVolume": false,
    "instanceSizeName": "M30",
    "regionName": "US_EAST_1"
  },
  "replicationFactor": 3,
  "stateName": "CREATING"
}

Now allow 5-10 minutes for your cluster to build. Once you've finished you can then list your available clusters via a simple GET. There's no need to POST anything here:

curl -i -u "jay.gordon:$APIKEY" --digest "[https://cloud.m575ece95e4b0ec4f28db42ca/clusters](https://cloud.m575ece95e4b0ec4f28db42ca/clusters)"

HTTP/1.1 200 OK
Date: Fri, 09 Dec 2016 16:45:23 GMT
Content-Length: 678
Content-Type: application/json
{
  "links": [
    {
      "href": "https:\/\/cloud.mongodb.com\/api\/atlas\/v1.0\/groups\/575ece95e4b0ec4f28db42ca\/clusters?pageNum=1&itemsPerPage=100",
      "rel": "self"
    }
  ],
  "results": [
    {
      "backupEnabled": true,
      "diskSizeGB": 40,
      "groupId": "575ece95e4b0ec4f28db42ca",
      "links": [
        {
          "href": "https:\/\/cloud.mongodb.com\/api\/atlas\/v1.0\/groups\/575ece95e4b0ec4f28db42ca\/clusters\/DataStore",
          "rel": "self"
        }
      ],
      "mongoDBMajorVersion": "3.2",
      "mongoDBVersion": "3.2.11",
      "mongoURIUpdated": "2016-12-09T16:41:16Z",
      "name": "DataStore",
      "numShards": 1,
      "providerSettings": {
        "providerName": "AWS",
        "diskIOPS": 120,
        "encryptEBSVolume": false,
        "instanceSizeName": "M30",
        "regionName": "US_EAST_1"
      },
      "replicationFactor": 3,
      "stateName": "CREATING"
    }
  ],
  "totalCount": 1
}

We can see it's creating and even programmatically add some delay into our script if we want to then load data once the cluster has finished building

Delete a Cluster:

We know how to list our clusters, so we can use the API to easily destroy the cluster when we are done with them using another curl POST:

bash-3.2$ curl -i -u "jay.gordon:$APIKEY" --digest -X DELETE 
"[https://cloud.mongodb.com/api/atlas/v1.0/groups/575ece95e4b0ec4f28db42ca/clusters/DataStore](https://cloud.mongodb.com/api/atlas/v1.0/groups/575ece95e4b0ec4f28db42ca/clusters/DataStore)"

Here's our output showing we've authenticated and completed our delete process:

HTTP/1.1 202 Accepted
Date: Fri, 09 Dec 2016 16:54:57 GMT
Content-Length: 2
Content-Type: application/json

Even More Resources:

You are not limited to just creating and deleting your cluster. You can use the API to modify other aspects such as the disk size or users while a cluster has already been created. You can review all of our API resources by going to the MongoDB Atlas API Documentation. Want even more MongoDB Atlas information? Check out M034 at MongoDB University for videos on how to use Atlas and start spinning up new MongoDB Clusters!

About the Author - Jay Gordon

Jay is a Technical Account Manager with MongoDB and is available via our chat to discuss MongoDB Cloud Products at https://cloud.mongodb.com.