Atlas Administration API Reference
On this page
The Atlas Administration API follows the principles of the REST architectural style to expose a number of internal resources which enable programmatic access to Atlas's features.
As with changes made through the Atlas web interface, changes made through the Atlas Administration API are subject to Atlas billing. If you incur charges, you must have a valid credit card on file with Atlas or risk having your account locked.
The API has the following features:
- Resource Versioning
Atlas provides versioned Atlas Administration API, which includes versioning at the individual Atlas Administration API resource-level. Use these resources and the following sections to learn more about the Atlas Administration API:
- JSON entities
- All entities are expressed in JSON.
- Key-based access
- Each Atlas user or application needing to connect to Atlas must generate an API key before accessing the Atlas Administration API.
- Digest authentication
- To ensure that your Atlas Administration API key is never sent over the network, Atlas Administration API requests are authenticated using HTTP Digest Authentication.
- Browsable interface
- Using a consistent linking mechanism, you can browse the entire Atlas Administration API by starting at the root resource and following links to related resources.
- HTTPS-Only
- You can only access the Atlas Administration API via HTTPS, ensuring all data sent over the network is fully encrypted using TLS.
- User Access Control
Each Atlas user's Atlas Administration API capabilities match the permissions granted by their Atlas Atlas User Roles.
Example
A user with the
Project Read Only
in a Atlas project can't modify any resource within that project whether through the Atlas user interface or the Atlas Administration API.- API Network Access List
Atlas can secure access to its Atlas Administration API through an API access list. This list restricts access to the API to specific IP or CIDR addresses. Each Programmatic API Key has its own Atlas Administration API access list. When you create a new organization using the Atlas UI, the Atlas enables the API access list requirement by default.
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 | Returns the response header without the JSON representation of
the resource. |
JSON
All entities are represented in JSON. The following rules and conventions apply:
Content Type Request Header
When sending JSON to the server via
POST
orPUT
, make sure to specify the correct content type request header:Content-Type: application/json
Invalid Fields
Invalid fields are rejected rather than ignored. For example, if you attempt to create a new entity and misspell one of the fields, or attempt to update an existing entity and include a field that can't be modified, the server responds with a 400 status code and an error message stating which field is invalid.
ISO-8601-Formatted Dates
All dates are returned as ISO-8601-formatted strings designated in UTC. When sending dates to the server (i.e., as query parameters or fields in
POST
orPATCH
request entities), use ISO-8601-formatted dates. If you do not specify a time zone, UTC is assumed. However, it is highly recommended that you include a time zone designator to avoid any ambiguity.BSON Timestamps
In some cases, a timestamp is returned as a BSON timestamp, most notably in the backup resources. These are represented in JSON documents as an object with two fields:
date
, which is an ISO-8601-formatted date string in UTC with granularity to the second, andincrement
a 32-bit integer.Field Names for Fields with Numbers
Fields that contain numeric values in a particular unit will be named so as to disambiguate the unit being used.
Empty Fields
Fields that do not have a current value are returned with an appropriate default value.
Fields that do not have a sensible default value are omitted from the entity.
Field Order
The fields in the JSON documents returned by the server are in no particular order, and the order may 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. 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 | Description |
---|---|
rel | Name (or type) of the relation. Many of these are considered
Extension Relation Types and are prefixed by
http://mms.mongodb.com . |
href | The 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, then it only
includes the self
link relation.
For more information, refer to the Web Linking Specification. Note that although the specification describes a format for including links in the HTTP response headers, doing so is not a requirement. To make the Atlas Administration 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. When a list of entities is expected in a response, the results are returned in batches bounded by the following query parameters:
Field | Description |
---|---|
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. |
includeCount | Specifies whether the response returns the totalCount field.
Defaults to true if not specified. |
The response entity contains three fields:
Field | Description |
---|---|
totalCount | The total number of items in the entire result set. |
results | The 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); and
self for the current page (always present). |
If you make a request for a list of entities and there are no results,
then the Atlas Administration API responds with a 200 status code and the results
array is empty. 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.
However, if you request a list of entities in a context that does not
exist (e.g., the list of hosts for a non-existent project), then this
does result in a 404 response status.
Envelopes
Some clients might 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 and contains any relevant details that would
normally be in the response headers. By default, the Atlas Administration 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 | Description |
---|---|
status | The HTTP status code. |
content | The requested entity. |
For responses that contain a list of entities, there is already an
envelope that wraps the results, so specifying envelope=true
only
adds the status
field to the existing envelope.
Pretty Printing
By default, extraneous whitespace is stripped from the JSON returned
by the server. 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/atlas/v1.0?pretty=true"
Response Codes
Responses use the standard HTTP response codes, including:
Code | Meaning | Notes |
---|---|---|
200 | OK | The request was successful. This is typically the response to a
successful GET request. |
201 | Created | A new resource was created. This is typically the 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
Atlas Administration 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. ExampleYou can't DELETE the root resource. |
409 | Conflict | This is 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. |
5xx | Various server errors | Something unexpected went wrong. Try again later and consider
notifying Atlas Support. |
Errors
When a request returns an error, the response body contains a JSON document. This document includes details about why the Atlas Administration API request failed. The document contains five parameters:
Parameter | Data Type | Description |
---|---|---|
detail | string | Human-readable description that Atlas returns for the errant
Atlas Administration API request. |
error | integer | Status code returned in the
header of the HTTP response. |
errorCode | string | Named constant that represents the errant Atlas Administration API
request. To learn about these constants, see
Atlas Administration API Error Codes. |
parameters | array | List of parameters included in the Atlas Administration API request. |
reason | string | Status code definition returned in
the header of the HTTP response. |
Example
Atlas returns the following response body when you make a request in the incorrect format:
1 { 2 "detail" : "Cannot find resource /api/atlas/v1.0/softwareComponents/version.", 3 "error" : 404, 4 "errorCode" : "RESOURCE_NOT_FOUND", 5 "parameters" : [ "/api/atlas/v1.0/softwareComponents/version" ], 6 "reason" : "Not Found" 7 }
Project ID
Your Project ID is a string value that uniquely identifies a Atlas project.
Atlas projects were previously identified as "groups". Some
Atlas endpoints reference group
or {GROUP-ID}
as part of
the request path, query, or body parameters. For any endpoint that
requires your {GROUP-ID}
, specify your Project ID instead.
To retrieve your project ID:
In Atlas, go to the Project Settings page.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
Next to the Projects menu, expand the Options menu, then click Project Settings.
The Project Settings page displays.
Authentication
The Atlas Administration API uses HTTP Digest Authentication to authenticate requests. Digest authentication requires a username and a password, where the API public key serves as the username and its corresponding API private key serves as the password. To learn more, see Atlas Administration API Authentication.
Configuring digest authentication for the Atlas Administration API differs
depending on the method you use to make API requests. If you use
cURL, include the --digest
flag in the request body.
For usage details, see Make an API Request.
Rate Limiting
Certain resources limit how many requests they can process per minute.
For these resources, Atlas allows up to 100 requests per minute per project. Atlas Administration API keys belong to an organization, but can be granted 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 are 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:01:00pm, requests to project X may proceed, because the request counter used for rate limiting resets each minute.
If you exceed the rate limit, the Atlas Administration API returns a 429 (Too Many Requests) HTTP status code.
Next Steps
To get started, see Get Started with the Atlas Administration API.
To manage programmatic access to the Atlas Administration API, see any of the following procedures: