Navigation
You were redirected from a different version of the documentation. Click here to go back.
  • API >
  • Public API Principles

Public API Principles

The Cloud Manager Public API follows the REST architecture principles to expose internal resources that provide programmatic access to Cloud Manager’s features.

As with changes made through the web interface, changes made through the API are subject to Cloud Manager pricing. If you add servers and incur charges, you must have a valid credit card on file with Cloud Manager or risk having your account locked.

The API has the following features:

JSON entities
All entities are expressed in JSON.
Key-based access
Each Cloud Manager user or application needing to connect to Cloud Manager must generate an API key before accessing the Cloud Manager API.
Digest authentication
To ensure that your Public API Key is never sent over the network, API requests are authenticated using HTTP Digest Authentication.
Browsable interface
Using a consistent linking mechanism, you can browse the entire API by starting at the root resource and following links to related resources.
User Access Control

Each Cloud Manager user’s API capabilities match the permissions that their Cloud Manager Roles grant.

Example

A user with the Project Read Only role cannot modify any resource within that project whether through the Cloud Manager UI or the API.

API Network Whitelist
The Cloud Manager API supports a per-user API Whitelist for restricting API access to specific IP or CIDR addresses. For Cloud Manager users with a non-empty API whitelist, all API access must originate from a whitelisted IP address. An empty API whitelist grants access to all API endpoints from any IP address, except those that explicitly require whitelisting for access.
HTTPS Only
You can only access the API via HTTPS, ensuring all data sent over the network is fully encrypted using TLS.

HTTP Methods

All resources support a subset of these common HTTP Methods:

Method Purpose
GET Retrieve the JSON representation of a resource.
POST Create a new resource using the provided JSON representation.
PUT Replace a resource with the provided JSON representation.
PATCH Update the specified fields in a resource using the provided JSON representation.
DELETE Remove a resource.
HEAD Retrieve the response header without the JSON representation of the resource.

JSON

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

Request Rules

Apply the Correct Content Type Header
When sending JSON to the server via POST or PUT, make sure to specify the correct content type request header: Content-Type: application/json
Set Dates as ISO 8601 Strings

When sending dates to the server (as query parameters or fields in POST or PATCH request entities), use dates formatted according to the ISO 8601 standard. If you don’t specify a time zone, Cloud Manager assumes UTC. Include a time zone designator to avoid any ambiguity.

Example

  • September 27, 2018 is expressed as 2018-09-27.
  • September 27, 2018 at 4:00 PM EDT is expressed (with time zone) as 2018-09-27T16:00-04:00.

In some cases, a timestamp is returned as a JSON representation of a BSON timestamp, most notably in the backup resources. This representation of a BSON timestamp provides a JSON document as an object with two fields:

Field Definition
date Seconds since the UNIX Epoch
increment An incrementing 32-bit integer ordinal for operations within a given second.

Example

The third operation at September 27, 2018 at 4:00 PM EDT is expressed (with time zone) as

{ date: 2018-09-27T16:00-04:00, increment: 3 }

Response Conventions

Rejects Invalid Fields

Invalid fields are rejected rather than ignored.

Example

You attempt to create a new entity and misspell one of the fields, or if you attempt to update an existing entity and include a field that cannot be modified, the Cloud Manager responds with an HTTP 400 status code and an error message stating which field was invalid.

Returns Dates as ISO 8601 Strings
All dates are returned as ISO 8601-formatted strings designated in UTC.
Labels Field to Disambiguate Units

Fields that contain numeric values in a particular unit are named so as to disambiguate the unit being used.

Example

A host’s uptime is returned in millseconds, so the name of the host entity field is uptimeMsec.

Returns Default Values for Fields without Other Values

Fields that do not have a current value are returned with an appropriate default value.

Example

Cloud Manager does not have any statistics for a newly discovered host, so any statistics-related fields have a value of zero.

Fields that do not have a sensible default value are omitted from the entity.

Example

A host that is not using authentication omits the username field from the returned entity.

Returns Fields in Alphabetical Order
The fields in the JSON documents that the Cloud Manager returns are in alphabetical order. The order could change. Do not depend on the order of the fields.

Linking

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

Example

A host has a link to the project it belongs to, the replica set it belongs to, and so on.

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

Field Definition
rel Name (or type) of the relation. Many of these are considered Extension Relation Types and are prefixed by http://mms.mongodb.com.
href Target URL.

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.

Example

This is a portion of a host resource with a few links:

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

To learn more, see the Web Linking Specification.

Note

Although the Web Linking Specification describes a format for including links in the HTTP response headers, it is not required. To make the API easily browsable, it includes the links in the response body rather than in the response headers.

Lists

Some resources return a list of entities.

Example

You can request a list of all hosts in a project.

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

Field Definition
pageNum Page number (1-based). Defaults to 1 if not specified.
itemsPerPage Number of items to return per page, up to a maximum of 500. Defaults to 100 if not specified.

The response entity contains three fields:

Field Definition
totalCount

Total number of items in the entire result set.

Example

If a project has a total of 57 hosts, and you make a request with pageNum=6 and itemsPerPage=10, then totalCount is 57.

results Result set, which is an array of entity documents.
links

Contains one to three link relations:

  • previous for the previous page of results (omitted for the first page);
  • next for the next page of results (omitted for the last page);
  • self for the current page (always present).

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.

Example

This is an HTTP response for the second page of 10 hosts in a project with a total of 57 hosts:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{

  "totalCount": 57,
  "results": [
    {
      "id": "yyy",
      "projectId": "xxx",
      // additional host properties...
    },
    // additional host documents...
  ],
  "links": [
    {
      "rel" : "self",
      "href" : "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?pageNum=2&itemsPerPage=10"
    },
    {
      "rel": "previous",
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=1"
    },
    {
      "rel": "next",
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=3"
    }
  ]
}

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:

Field Definition
status HTTP status code.
content Requested entity.

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 '{USERNAME}:{APIKEY}' --digest \
 --header 'Accept: application/json' \
 --include \
 --request GET "https://cloud.mongodb.com/api/public/v1.0?pretty=true"

Note

All the examples in this document show pretty-printed JSON for clarity, although some example URLs may not contain this additional query parameter.

Response Codes

Responses utilize the standard HTTP response codes, including:

Code Meaning Notes
200 OK The request was successful. This is the typical response to a successful GET request.
201 Created A new resource was created. This is the typical response to a successful POST request.
202 Accepted A request for an asynchronous operation was accepted.
400 Bad Request Something was wrong with the client request.
401 Unauthorized Authentication is required but was not present in the request. Typically this means that the digest authentication information was omitted from the request, the provided credentials are incorrect, or the user associated with the given API key is not allowed to access the requested resource.
403 Forbidden Access to the specified resource is not permitted.
404 Not Found The requested resource does not exist.
405 Method Not Allowed

The HTTP method is not supported for the specified resource. Keep in mind that each resource may only support a subset of HTTP methods.

Example

You are not allowed to DELETE the root resource.

409 Conflict

This is typically the response to a request to create or modify a property of an entity that is unique when an existing entity already exists with the same value for that property.

Example

If you attempt to create a project with the same name as an existing project, the request fails.

5xx Various server errors Something unexpected went wrong. Try again later and consider notifying Cloud Manager Support.

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:

Field Data Type Definition
detail string Human-readable description of the API request error.
error integer HTTP status code.
errorCode string Named constant representing the API request error as shown in Public API Error Codes.
parameters array of strings List of parameters passed in the API request.
reason string HTTP status code definition.

Example

Cloud Manager returns this response body for an incorrectly formatted request:

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

To review the list of codes, see Public API Error Codes.

Authentication

As previously mentioned, the Cloud Manager API uses HTTP Digest Authentication. The details of digest authentication are beyond the scope of this document, but it essentially requires a username and a password which are hashed using a unique server-generated value called a nonce. The username is the username of a registered Cloud Manager account, and the password is a Public API Key associated with that account.

Keep the following points in mind:

  • The server-generated nonce is used by the client to hash the username and password before sending them back to the server to authenticate a request. The nonce is only valid for a short amount of time as per the digest authentication specification. This is to prevent replay attacks, so you cannot cache a nonce and use it forever.
  • Using digest authentication in combination with HTTPS provides an extra layer of security by ensuring that a password is never transmitted back to the server.
  • Some resource methods require even more security and are additionally protected by whitelists that allow access to the resource only from the IP addresses listed. Each user configures their own whitelist of IP addresses that allow access to the resource.

  • The Cloud Manager has a concept of roles, which allow more fine-grained control of the operations a user is allowed to perform. The API resources also enforce the same authorization rules, so the resources and methods that can be accessed by an API key are governed by the roles granted to the associated user.

    Example

    To DELETE a host, the user that owns the API key used to make the request must be a Project Monitoring Admin or Project Owner in the project to which the host belongs.

  • Many resources are tied to a project (former known as a group), as evidenced by URLs of the following form:

    /api/public/v1.0/groups/{PROJECT-ID}/
    

    For these resources, the user tied to the API key must be a member of the project. Otherwise Cloud Manager responds with an HTTP 401 error.

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.

Important

There is no protection in the API to prevent concurrent modifications. If two administrators both start with a configuration based on the current version, make their own modifications, and then submit their modifications, the later modification wins.

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.

Example

Consider two users: A and B.

User A belongs to project X, and user B belongs to projects X and Y.

  1. At 1:00:00pm, User A makes 50 requests to a rate limited resource in project X, all of which complete by 1:00:20pm.

  2. At 1:00:30pm, User B attempts to make 60 requests to a rate limited resource in project X.

    Since User A has already used up 50 requests within the 1:00pm minute for project X, the last 10 requests User B attempts to make are rejected. However, User B can make requests to a rate limited resource in project Y, since each project maintains a separate request counter.

  3. At 1:01pm, requests to project X may proceed, because the request counter used for rate limiting reset each minute.

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

Additional Information

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

←   API Public API Resources  →