Public API Principles

HTTP Methods

All resources support a subset of these common HTTP Methods:

JSON

All entities are represented in JSON. The following rules for requests and conventions of responses apply:

Linking

Each resource includes one or more links to sub-resources and/or related resources.

Links are placed in the links field of an entity, which is an array of link relation objects. Each link relation has two fields:

All entities include at least one link relation called self, which is simply its own URL. When an entity is part of a list (i.e., when requesting all hosts in a project), then it only includes the self link relation.

1
{
2
  "id": "xxx",
3
  "projectId": "yyy",
4
  "hostname": "mongodb.example.com",
5
  "port": 27017,
6
  "links": [
7
    {
8
      "rel": "self",
9
      "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx/hosts/yyy"
10
    },
11
    {
12
      "rel": "http://mms.mongodb.com/project",
13
      "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx"
14
    }
15
  ]
16
}

To learn more, see the Web Linking Specification.

Lists

Some resources return a list of entities.

When a list of entities is expected in a response, the results are returned in batches bounded by two query parameters:

The response entity contains three fields:

If you make a request for a list of entities and there are no results, then the API responds with an HTTP 200 status code and an empty results array. It does not respond with a 404 in this case, since the list of entities may not be empty at some point in the future.

If you had requested a list of entities in a context that does not exist (i.e., the list of hosts for a non-existent project), then this results in a an HTTP 404 response status.

1
{
2
3
  "totalCount": 57,
4
  "results": [
5
    {
6
      "id": "yyy",
7
      "projectId": "xxx",
8
      // additional host properties...
9
    },
10
    // additional host documents...
11
  ],
12
  "links": [
13
    {
14
      "rel" : "self",
15
      "href" : "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?pageNum=2&itemsPerPage=10"
16
    },
17
    {
18
      "rel": "previous",
19
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=1"
20
    },
21
    {
22
      "rel": "next",
23
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=3"
24
    }
25
  ]
26
}

Envelopes

Some clients may not be able to access the HTTP response headers and/or status code. In that case, you can request that the response include an envelope, which is simply an extra layer of information in the JSON document that contains any relevant details that would normally be in the response headers.

By default, the API does not include the response in an envelope. To request one, simply add the query parameter envelope=true.

For responses that contain a single entity, the envelope contains two fields:

For responses that contain a list of entities, there is already an envelope that wraps the results, so specifying envelope=true as a query parameter in this case only adds the status field to the existing envelope.

Pretty Printing

By default, extraneous whitespace is stripped from the JSON that Cloud Manager returns. To ask for pretty-printed JSON, simply append the pretty=true query parameter to any request:

curl --user '{PUBLIC-KEY}:{PRIVATE-KEY}' --digest \
 --header 'Accept: application/json' \
 --include \
 --request GET "https://cloud.mongodb.com/api/public/v1.0?pretty=true"

Response Codes

Responses utilize the standard HTTP response codes, including:

Errors

When a request results in an error, the response body contains a JSON document with additional details about what went wrong. The document contains five fields:

1
{
2
  "detail" : "Cannot find resource /api/public/v1.0/softwareComponents/version.",
3
  "error" : 404,
4
  "errorCode" : "RESOURCE_NOT_FOUND",
5
  "parameters" : [ "/api/public/v1.0/softwareComponents/version" ],
6
  "reason" : "Not Found"
7
}

To review the list of codes, see Cloud Manager Administration API Error Codes.

Authentication

The Cloud Manager API uses one of two methods to authenticate requests: API keys or service accounts. This ensures that the keys and access tokens that serve as usernames and passwords are never sent over the network. For usage details, see Programmatic Access to Cloud Manager.

Some resource methods require even more security and are additionally protected by access lists that allow access to the resource only from the IP addresses listed. Each user configures their own access list of IP addresses that allow access to the resource.

Automation

The Automation Configuration Resource and Get Automation Status of Latest Plan resources provide endpoints that let you modify a project's deployment and retrieve deployment status. You can modify a deployment by sending a new automation configuration to Cloud Manager. The automation configuration is where you describe and configure the MongoDB processes to be deployed. Cloud Manager refers to this as the deployment's "goal state." When you submit a new automation configuration through the API, the Automations adjust the current state of the system to match the goal state.

Rate Limiting

Certain resources are subject to rate limiting.

For resources that are rate limited, Cloud Manager allows up to 100 requests per minute per project. Keep in mind that a Public API Key is assigned to a Cloud Manager user, but that user may access multiple projects.

If you exceed the rate limit, the API returns an HTTP 429 Too Many Requests response code.

Additional Information

See Cloud Manager Administration API Resources for a complete reference of all resources available in the Cloud Manager Public API.