Integrating with Cloudant

improve this page | report issue


Cloudant is a NoSQL Database based on CouchDB, which is available as a stand-alone product as well as a Database-as-a-Service (DBaaS) on IBM Cloud and

As described in the Cloudant documentation:

Documents are JSON objects. Documents are containers for your data, and are the basis of the Cloudant database.
All documents must have two fields: a unique _id field, and a _rev field. The _id field is either created by you, or generated automatically as a UUID by Cloudant. The _rev field is a revision number, and is essential to the Cloudant replication protocol. In addition to these two mandatory fields, documents can contain any other content expressed as JSON.

The Cloudant API is documented on the IBM Cloudant Documentation site.

You can use adapters to communicate with a remote Cloudant database. This tutorial shows you some examples.

This tutorial assumes that you are comfortable with adapters. See JavaScript HTTP Adapter or Java Adapters.

Jump to

JavaScript HTTP adapter

The Cloudant API can be accessed as a simple HTTP web service.

Using an HTTP adapter, you can connect to the Cloudant HTTP service with the invokeHttp method.


Cloudant supports several forms of authentication. See the Cloudant documentation about authentication at With a JavaScript HTTP adapter, you can use Basic Authentication.

In your adapter XML file, specify the domain for your Cloudant instance, the port and add an authentication element of type basic. The framework will use those credentials to generate an Authorization: Basic HTTP header.

Note: With Cloudant, you can generate unique API keys to use instead of your real username and password.

  <connectionPolicy xsi:type="http:HTTPConnectionPolicyType">
    <!-- Following properties used by adapter's key manager for choosing specific certificate from key store


Your adapter procedures use the invokeHttp method to send an HTTP request to one of the URLs that are defined by Cloudant.
For example, you can create a new document by sending a POST request to /{*your-database*}/ with the body being a JSON representation of the document that you wish to store.

function addEntry(entry){

    var input = {
            method : 'post',
            returnedContentType : 'json',
            path : DATABASE_NAME + '/',
            body: {
                contentType : 'application/json',        
                content : entry

    var response = MFP.Server.invokeHttp(input);
        response.isSuccessful = false;
    return response;


The same idea can be applied to all Cloudant functions. See the Cloudant documentation about documents at

Java adapters

Cloudant provides a Java client library for you to easily use all the features of Cloudant.

During the initialization of your Java adapter, set up a CloudantClient instance to work with.
Note: With Cloudant, you can generate unique API keys to use instead of your real username and password.

CloudantClient cloudantClient = new CloudantClient(cloudantAccount,cloudantKey,cloudantPassword);
db = cloudantClient.database(cloudantDBName, false);

Using Plain Old Java Objects and standard Java API for RESTful Web Services (JAX-RS 2.0), you can create a new document on Cloudant by sending a JSON representation of the document in the HTTP request.

public Response addEntry(User user){
    if(user!=null && user.isValid()){;
        return Response.ok().build();
        return Response.status(418).build();

Image of the sample application

Sample application

Click to download the Cordova project.

The sample contains two adapters, one in JavaScript and one in Java.
It also contains a Cordova application that works with both the Java and JavaScript adapters.

Note: The sample uses Cloudant Java Client v1.2.3 due to known limitation.

Sample usage

Follow the sample’s file for instructions.

Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on March 28, 2018