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
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:
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:
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:
Note
All the examples in this document show pretty-printed
JSON
for
clarity, although some example
URL
s
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
Cloud Manager Administration 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:
To review the list of codes, see
Cloud Manager Administration 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
URL
s of the following form:
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.