API >
Public API Principles

Public API Principles¶

On this page

HTTP Methods
JSON
Linking
Lists
Envelopes
Pretty Printing
Response Codes
Errors
Authentication
Automation
Additional Information

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

copy

{ 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:

copy

{
  "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:

copy

{

  "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:

copy

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:

{
  "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:
copy
```
/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.

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.
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.
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 →

Cloud Manager will no longer support Automation for MongoDB 3.4 clusters after February 10, 2022. Please upgrade your MongoDB deployment or migrate to Atlas.

Public API Principles¶

HTTP Methods¶

JSON¶

Request Rules¶

Response Conventions¶

Linking¶

Lists¶

Envelopes¶

Pretty Printing¶

Response Codes¶

Errors¶

Authentication¶

Automation¶

Rate Limiting¶

Additional Information¶