Overview

mLab databases can be accessed by applications in two ways.

The first method - the one we strongly recommend - is to connect using one of the available MongoDB drivers. You do not need to use our API if you use the driver. In fact, using a driver provides better performance, better security, and more functionality.

The second method, documented in this article, is to connect via mLab’s RESTful Data API. Use this method only if you cannot connect using a MongoDB driver.

Each mLab account comes with a Data API (disabled by default) that can be used to access the databases, collections and documents belonging to that account. The API exposes most of the operations you would find in the MongoDB driver, but offers them as a RESTful interface over HTTPS.

Furthermore, each user of an account has his own API key that can be used to access the API. Users can view or reset their API keys through the management portal and Admin users can also view or reset API keys for all users of an account.

API Authentication

Each API request must pass an apiKey query parameter. By default, access to the Data API is disabled and must be enabled before you can obtain your API key.

If you are already in the Account Settings page, then click on the row with your username in the Account Users section.

If the status is showing as “Data API Access: Disabled” in the “API Key” section, click the “Enable Data API access” button.

Once Data API access is enabled, your current API key will be displayed in the “API key” field.

(Optional) If you want to update the current key, click the “Regenerate API key” button.

Your API key will give full access to all data within the databases belonging to your mLab account. If you distribute it to untrusted individuals, they can gain access to your account and your data.

We have seen customers distribute mobile and AJAX-based web applications to their end users. Doing this will expose your account to attack. Such clients are appropriate only when you can control their distribution to just mLab account users.

Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

List collections

Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

List documents

To get the documents in the specified collection. If no parameters are passed, it lists all of them. Otherwise, it lists the documents in the collection matching the specified parameters:

GET /databases/{database}/collections/{collection}
Example listing all documents in a given collection:
https://api.mlab.com/api/1/databases/my-db/collections/my-coll?apiKey=myAPIKey
Optional parameters
[q=<query>][&c=true][&f=<fields>][&fo=true][&s=<order>][&sk=<skip>][&l=<limit>]

Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

Create collection

To create a new collection, just start using it! Just like using a standard driver or the shell, collections are created implicitly just by using them. As soon as you POST your first document you should see the collection appear.

Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

If you POST a document that contains an _id field, the effect will be to overwrite any existing document with that _id. When your document already includes an _id value, think of POST like “save” or “upsert” (discussed below) rather than “create” or “insert”.

One consequence of this behavior: for a document with an _id specified, there is no straightforward way in the API to realize a pure “insert” — that is, an operation that refuses to modify a pre-existing document with that _id. POST will save over the old document; PUT will modify it. If this property is problematic for your application, consider using a field other than _id, with its own index to enforce uniqueness.

Insert multiple documents

To add multiple documents to the specified collection, specify a list of documents in the data payload:

So, you can think of PUT like “update”; with u=true added, it becomes “update or insert”, or “upsert” for short.

Delete/replace multiple documents

To replace the contents of some or all of a collection, use a PUT request with a replacement list of documents in the body. An optional query in the q parameter can be used to replace a subset of the collection. Specifying an empty list in the body is equivalent to deleting the documents matching the query.

Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

Modifies the document matching the specified _id. If no document matching the specified _id already exists, it creates a new document. The data payload should contain a replacement document or update modifiers (MongoDB reference):

Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

Run database and collection-level commands

To run a MongoDB database command, send a POST request to the runCommand endpoint. Only certain MongoDB commands are exposed through the Data API. If there are other commands you need to run, you can always use the mongo shell or a standard MongoDB driver instead. The available commands are:

Note: in version 1 of the API (i.e., resource paths beginning with /api/1), all successful operations return code 200, even when new resources have been created. However, future API versions will use this 201 code as described.

400 - Bad Request

Returned whenever a request cannot be fulfilled because of an error with the input

401 - Unauthorized

Returned either when no user credentials could be found or the credentials found are not authorized to perform the requested action

403 - Forbidden

Returned whenever the server is refusing access to a resource, usually because the user does not have permissions to it

404 - Not Found

Returned whenever the resource being requested does not exist

405 - Method Not Allowed

Returned whenever the HTTP method (e.g. GET or POST) is not supported for the resource being requested

UTF-8 Characters

The API does support UTF-8 characters. As per the HTTP spec, you need to be sure to explicitly set the character set you are using in the Content-Type header. The default character set (ISO-8859-1) is not very i18n friendly.

Here’s an example of posting special characters using the UTF-8 character set.

Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

I cannot update a document using the mLab API from an AngularJS application

The contents of this section are gratefully borrowed from the experience of one of our beloved mLab customers.

You’re using the mLab API from your AngularJS application, and inserts, gets, and deletes are working with no issues using the $.ajax() function. However, updating an existing document is not working.

It turns out things work a little differently for the HTTP PUT verb, which is used to perform updates through the API. You can’t just supply type: “PUT” to the $.ajax() function — you have to use a different function altogether.

The code below performs a document update to the “party” document with id $scope.id using angularjs: