REST API for MongoLab

Overview

MongoLab databases can be accessed by applications in two ways. The first method - the one we strongly recommend - is to connect via one of the available MongoDB drivers. You do not need to use our API if you use the driver.

The second method, which you should use only if you cannot connect via one of the MongoDB drivers, is via MongoLab’s RESTful API, documented here.

Each MongoLab account comes with a REST API that can be used to access the databases, collections and documents belonging to that account. The API exposes most 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. Follow these steps to obtain your API key:

  1. Log in to the MongoLab management portal
  2. Click your username (not the account name) in the upper right-hand corner to open your account user profile
  3. In the section titled “API Key”, your current API key is displayed at the bottom which you can cut-and-paste img-apikey
  4. Optional: If you want to update the current key, click “Regenerate API key”

Your API key will give full access to all data within the databases belonging to your MongoLab 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 MongoLab account users.

Here’s an example of a complete Resource URL:

https://api.mongolab.com/api/1/databases?apiKey=2E81PUmPFI84t7UIc_5YdldAp1ruUPKye

Base URL Path

All API paths listed below are relative to the following base URL path:

Fixed portion of the Resource URL:
https://api.mongolab.com/api/1

API Reference

List databases

To get the databases linked to the authenticated account:

GET /databases

Example:
https://api.mongolab.com/api/1/databases?apiKey=myAPIKey
     Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

To get all the databases for a cluster linked to the authenticated account:

GET /clusters/{cluster}/databases

Example:
https://api.mongolab.com/api/1/clusters/cluster-id/databases?apiKey=myAPIKey

Where "cluster-id" is in the form of "rs-<cluster>" (e.g., rs-ds012345)
     Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

List collections

To get the collections in the specified database:

GET /databases/{database}/collections

Example:
https://api.mongolab.com/api/1/databases/my-db/collections?apiKey=myAPIKey
     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.mongolab.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.

Optional parameters (MongoDB reference):

Examples using these parameters:

"q" example - return all documents with "active" field of true:
https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?q={"active": true}&apiKey=myAPIKey

"c" example - return the count of documents with "active" of true:
https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?q={"active": true}&c=true&apiKey=myAPIKey

"f" example (include) - return all documents but include only the "firstName" and "lastName" fields:
https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?f={"firstName": 1, "lastName": 1}&apiKey=myAPIKey

"f" example (exclude) - return all documents but exclude the "notes" field:
https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?f={"notes": 0}&apiKey=myAPIKey

"fo" example - return a single document matching "active" field of true:
https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?q={"active": true}&fo=true&apiKey=myAPIKey

"s" example - return all documents sorted by "priority" ascending and "difficulty" descending:
 https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?s={"priority": 1, "difficulty": -1}&apiKey=myAPIKey

"sk" and "l" example - sort by "name" ascending and return 10 documents after skipping 20
 https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?s={"name":1}&sk=20&l=10&apiKey=myAPIKey
     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.

Insert document

To create a new document in the specified collection:

jQuery reference
POST /databases/{database}/collections/{collection}
Content-Type: application/json
Body: <JSON data>

Example (using jQuery):

$.ajax( { url: "https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?apiKey=myAPIKey",
		  data: JSON.stringify( { "x" : 1 } ),
		  type: "POST",
		  contentType: "application/json" } );
     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:

jQuery reference
POST /databases/{database}/collections/{collection}
Content-Type: application/json
Body: <JSON data>

Example (using jQuery):

$.ajax( { url: "https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?apiKey=myAPIKey",
		  data: JSON.stringify( [ { "x" : 1 }, { "x" : 2 }, { "x" : 3 } ] ),
		  type: "POST",
		  contentType: "application/json" } );
     Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

Update multiple documents

To update one or more documents in the specified collection, use a PUT request with a replacement document or update modifiers in the body (MongoDB reference):

PUT /databases/{database}/collections/{collection}
Content-Type: application/json
Body: <JSON data>

Example setting "x" to 3 in the document with "_id" = 1234 (using jQuery):

$.ajax( { url: 'https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?apiKey=myAPIKey&q={"_id":1234}',
		  data: JSON.stringify( { "$set" : { "x" : 3 } } ),
		  type: "PUT",
		  contentType: "application/json" } );

Optional parameters:
[q=<query>][&m=true][&u=true]
     Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

Optional parameters:

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.

jQuery reference
PUT /databases/{database}/collections/{collection}
Content-Type: application/json
Body: <JSON data>

Example (using jQuery):

$.ajax( { url: 'https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?apiKey=myAPIKey',
		  data: JSON.stringify( [ { "x" : 1 }, { "x" : 2 }, { "x" : 3 } ] ),
		  type: "PUT",
		  contentType: "application/json" } );

Optional parameters:
[q=<query>]
     Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

Optional parameters:

View, update or delete a single document

Returns the document with the specified _id:

GET /databases/{database}/collections/{collection}/{_id}

Example:
https://api.mongolab.com/api/1/databases/my-db/collections/my-coll/4e7315a65e4ce91f885b7dde?apiKey=myAPIKey 
     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):

jQuery reference
PUT /databases/{database}/collections/{collection}/{_id}
Content-Type: application/json 
Body: <JSON data>

Example replace the matching document with { "x" : 2 } (using jQuery): 

$.ajax( { url: "https://api.mongolab.com/api/1/databases/my-db/collections/my-coll/4e7315a65e4ce91f885b7dde?apiKey=myAPIKey",
		  data: JSON.stringify( { "x" : 2 } ),
		  type: "PUT",
		  contentType: "application/json" } );

Example setting "y" to 5 in the matching document without affecting other fields (using jQuery): 

$.ajax( { url: "https://api.mongolab.com/api/1/databases/my-db/collections/my-coll/4e7315a65e4ce91f885b7dde?apiKey=myAPIKey",
		  data: JSON.stringify( { "$set" : { "y" : 5 } } ),
		  type: "PUT",
		  contentType: "application/json" } );
     Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

Deletes the document with the specified _id:

cURL reference, jQuery reference
DELETE /databases/{database}/collections/{collection}/{_id}

Example (using cURL): 
curl -X DELETE 'https://api.mongolab.com/api/1/databases/my-db/collections/my-coll/4e7315a65e4ce91f885b7dde?apiKey=myAPIKey

Example (using jQuery):

$.ajax( { url: "https://api.mongolab.com/api/1/databases/my-db/collections/my-coll/4e7315a65e4ce91f885b7dde?apiKey=myAPIKey",
		  type: "DELETE",
		  async: true,
		  timeout: 300000,
		  success: function (data) { },
		  error: function (xhr, status, err) { } } );
     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 REST 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:

jQuery reference
POST /databases/{database}/runCommand
Content-Type: application/json
Body: <JSON data>

Example (using jQuery):
The following returns a list of distinct values for 'account' in the 'users' collection matching {"active": true}.

$.ajax( { url: "https://api.mongolab.com/api/1/databases/my-db/runCommand?apiKey=myAPIKey",
		  data: JSON.stringify( {"distinct": "users","key": "account","query": {"active":true}} ),
		  type: "POST",
		  contentType: "application/json",
		  success: function(msg) {
			   alert( msg );
		  } } )
     Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

HTML Status Codes

The API commonly returns the following codes. For further reference, see W3C’s documentation.

200 - OK
Returned whenever a resource is listed, viewed, updated or deleted
201 - Created
Returned whenever a resource is created (instead of code 200)
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.

jQuery reference
POST /databases/{database}/collections/{collection}
Content-Type: application/json;charset=utf-8
Body: <JSON data>

Example (using jQuery):

$.ajax( { url: "https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?apiKey=myAPIKey",
		  data: JSON.stringify( { "Iñtërnâtiônàlizætiøn" : true } ),
		  type: "POST",
		  contentType: "application/json;charset=utf-8" } );
     Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.

Troubleshooting

How do I insert a date in a REST call?

Dates for use in MongoDB documents can be constructed as ISO UTC strings with special $date key. The field might look like:

{"myDate": {"$date": "2010-07-20T23:23:50Z"}}

So, a “book” document with a published_date might look like:

{"bookTitle": "How to insert dates", 
 "publishedDate": {"$date": "2010-07-20T23:23:50Z"}, 
 "authorName": "Robert"}

If you’re open to using a JavaScript Library, try DateJS. There’s a Google resource that describes the methods of the DateSJ Date class, particularly the toISOString method. Here’s an example:

$.ajax( { url: "https://api.mongolab.com/api/1/databases/my-db/collections/my-coll?apiKey=myAPIKey", 
		  data: JSON.stringify({"lat": 41.23, "long": 2.23, "time": {"$date": new Date().toISOString()}}), 
		  type: "POST", 
		  contentType: "application/json" } );
     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 MongoLab API from an AngularJS application

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

You’re using the MongoLab 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:

$http.put('https://api.mongolab.com/api/1/databases/YOUR_DB/collections/THE_PARTY_COLLECTION/'; + 
           $scope.id + '?apiKey=YOUR_MONGOLAB_API_KEY',
	  { 'Address': $scope.party.Address,
		'Date': $scope.party.Date,
		'Link': $scope.party.Link,
		'Photo': $scope.party.Photo
	  }).success(function (data, status, headers, config) {
				   $scope.refreshGrid();
				   $scope.id = '';
				   $scope.party = {}
				   $scope.SaveButton = "Add";
	  }).error(function (data, status, headers, config) { alert(status) });
     Your API key, including any clients from which your API key can be recovered, should not be distributed to non-administrators.