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
  "rel": "http://mms.mongodb.com/project",
3
  "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx"
4
  "id": "xxx",
5
  "projectId": "yyy",
6
  "hostname": "mongodb.example.com",
7
  "port": 27017,
8
  "links": [
9
    {
10
      "rel": "self",
11
      "href": "https://<ops-manager-host>/api/public/v1.0/projects/xxx/hosts/yyy"
12
    },
13
    {
14
      "rel": "http://mms.mongodb.com/project",
15
      "href": "https://<ops-manager-host>/api/public/v1.0/projects/xxx"
16
    }
17
  ]
18
}

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 Ops 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 "{opsManagerHost}:{Port}/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 Ops Manager Administration API Error Codes.

Authentication

As previously mentioned, the Ops 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 Ops 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.

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

• The Ops Manager Application 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 or must be assigned to one of the GLOBAL roles. Otherwise Ops Manager Application 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 Ops Manager. The automation configuration is where you describe and configure the MongoDB processes to be deployed. Ops 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.

Additional Information

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