Click here to Skip to main content
15,607,524 members
Articles / Internet of Things
Posted 9 Jun 2016



Getting Started with Cloudant

9 Jun 2016CPOL7 min read
Cloudant is a NoSQL database as a service (DBaaS) built from the ground up to scale globally, running non-stop, and handling a wide variety of data types.

This article is in the Product Showcase section for our sponsors at CodeProject. These articles are intended to provide you with information on products and services that we consider useful and of value to developers.

Image 1

This article is the first of several tutorials on IBM Cloudant. This article is an introduction for Cloudant, explaining the preliminary things you need to know when starting with IBM Cloudant. It also contains information about the base CRUD operations that you need to use in solutions using this database.

Clodant is an open source NoSQL database, realised as a distributed database of the same name. This service is based on opensource projects Apache CouchDB and BigCouch projects.

This article is the first one of five, focused on practical examples of how to start with IBM Cloudant and how to use it in real life IoT solutions.

While Cloudant can be used with a variety of platforms and languages, this particular series is based on solutions implemented with .NET and Microsoft Azure.

This set of tutorials will be very useful for a variety of professionals:

  • Developers who want to use Cloudant with .NET and/or Microsoft Azure
  • Architects who use IBM Cloudant in different solutions
  • Different specialists (developers, architects, business analysts) who work on Internet of Things (IoT) solutions

These articles can also be useful for all specialists who want to know more about Cloudant and/or IoT Solutions.

The source code of the examples will be provided for download to help readers to better understand the concept and the implementation details.


In the last several years we have seen more and more data-centric solutions with a variety of use cases/needs, including:

  • to have the option to store a huge amount of data at a reasonable price
  • to have scalable data storage
  • to be possible to search via different properties (to support many indexes)
  • for the database to be highly available - to make it possible to provide Service Level Ageement (SLA) regarding the maximum downtime per year, allowed for the solution
  • for the database to be realised as SaaS (Software as a Service) to offer further support and maintenance

All these requirements allow you to consider a specific kind of NoSQL database that is also cloud-based. The solution is "specific" because on one hand we need to use analysis where we search using different indexes, but on the other hand we need good scalability. One of the best options for this kind of solution is to use a document-oriented database. This solution is designed for storing, retrieving, and managing document-oriented information, also known as semi-structured data.

There are several popular document-oriented databases like MongoDB, CoachDB, DocumentDB, Cloudant (based on CoachDB). These solutions have different implementations based on their cloud platform. IBM Cloudant is the subject of this series of articles.


Image 2

Before you start ensure you have:

  • Cloudant account
  • Visual Studio 2015
  • Microsoft Azure account

You need to have a valid Cloudant account. If you don’t have an IBM Cloudant subscription you can create one on You can try this database for free for 30 days. After the trial, Cloudant offers metered pricing and your first $50 USD of usage each month is free.

As you set up your Cloudant account, you will notice in the "data location" section that Cloudant can be deployed over different cloud platforms. For the purpose of these tutorials, we will use a Western US location, implemented over Microsoft Azure. However, it is possible to use different cloud platforms including IBM SoftLayer and Rackspace, among others.

Please bear in mind that for most of the solutions, the geographic location of the data center (in regard to your own solution) is the most important criterion when you are choosing your data location. Network latency between the data center and your users can be minimized by selecting a data center closest to your primary users.

Another important consideration can be the platform. Understand the pricing structure (each cloud platform charges internal and external traffic differently) and choose the best one for your product/solution.

Image 3

All examples are written in C# and implemented using Visual Studio 2015. If you do not have Visual Studio, the community edition is a good option and can be downloaded for free at:

And finally, you will need a Microsoft Azure account. You can create a free trial here:

Setup your Cloudant database

The following is a brief description of how to use the article or code: The class names, the methods and properties, and any tricks or tips.

When you are logged in the Cloudant portal you can see the existing databases. There are two preset databases: _users and _replicator, that will be discussed in the next tutorials.

You can also filter the databases by name.

Image 4

You can create a new database by choosing the "Create Database" control. After that you need to write in the name of the new database. Only lower case letters and numbers are allowed in the name.

Image 5

When you have created a new database it is possible to manage this database via the portal using queries, or by changing indexes, permissions etc.

Image 6

The Application

The application created for this article series is a simple IoT solution implemented with C# and contains the following parts (see the picture below):

  • Managed objects (sensors), that measure specific values like temperature, speed, displacements, etc.
  • Gateways: devices that collects information from sensors and communicates via
  • Back office – set of services and applications that are used to ingress, process and store data, manage and monitor the whole solution.

The simple prototype used for this article includes:

  • Simulated gateway (.NET application)
  • Gateway service: a web service, implemented on .NET and hosted in Microsoft Azure, that communicates with the gateway and stores data to the IBM Cloudant.
  • IBM Cloudant database
  • Web Application to visualize the collected data from Cloudant

Image 7

Using the Code

A simple .NET application was created to demonstrate the basic CRUD operations via Cloudant REST API. The whole source code of the source application is availabale in GitHub .

The application saves in IBM Cloudant JSON documents after it reads these documents and updates the documents in database. The Delete option is also demonstrated.

This application is very basic and doesn't use any specific frameworks. It just uses HttpClient and HttpClientHandler to communicate via the REST interface with the Cloudant database. HttpClient is a modern HTTP client for .NET. It provides a flexible and extensible API for accessing all things exposed through HTTP.

Some things to note:

  • The HttpClientHandler class is used to implement a HTTP handler. It is the process (frequently referred to as the "endpoint") that runs in response to a request made to a .NET Web application.
  • There is a helper class Sensor. It is used to manage data from sensors (we will reuse it in the IoT solution in the next tutorials).
  • This class contains data on the humidity, temperature, displacement and the time when these values are measured from a specific sensor.
  • A seed method "Generate" is implemented to generate random values from simulated sensors.
#region Sensor
/// <summary>
/// Sensor class
/// this class is used to manage data from sensors
/// </summary>
public class Sensor
    public string time;
    public string dspl;
    public int temp;
    public int hmdt;

    static Random R = new Random();
    static string[] sensorNames = new[] { "sensorA", "sensorB", "sensorC", "sensorD", "sensorE" };

    public static Sensor Generate()
        return new Sensor { time = DateTime.UtcNow.ToString(), dspl = sensorNames[R.Next(sensorNames.Length)], temp = R.Next(70, 150), hmdt = R.Next(30, 70) };

    public static Sensor Update(Sensor sensor, string revision)
        return new Sensor { time = sensor.time, dspl = sensor.dspl, temp = sensor.temp, hmdt = sensor.hmdt };
#endregion Sensor

In the main program credentials for the Cloudant database are passed as parameters. You need to create a HttpClientHandler. It is an HttpMessageHandler with a common set of properties that works across most versions of the HttpWebRequest API.

This program also adds an implementation of the main CRUD operations.

static void Main(string[] args)


     //read config data from a command line parameters

     var user = args[0];

     var password = args[1];

     var database = args[2];

     //base request builder for all requests containing user name and database name

     var handler = new HttpClientHandler { Credentials = new NetworkCredential(user, password) };

     //create an http client

     using (var client = CreateHttpClient(handler, user, database))


       //implement CRUD operations



The CreatehttpClient method is used to create an HttpClient that is used to handle the CRUD operations. The default HttpClient is the simplest way in which you can start sending requests. A single HttpClient can be used to send as many HTTP requests as you want concurrently so in many scenarios you can just create one HttpClient and then use that for all your requests.

#region CreateHttpClient
private static HttpClient CreateHttpClient(HttpClientHandler handler, string user, string database)
    return new HttpClient(handler)
        BaseAddress = new Uri(string.Format("https://{0}{1}/", user, database))
#endregion CreateHttpClient

The code below demonstrates how to provide CRUD operations with simple JSON documents. To make the code easier to read, four helper functions are implemented: "Create", "Read", "Update", "Delete".

#region manage simple json document

var creationResponse = Create(client, new { name = "john", age = 15 });

var id = GetString("id", creationResponse);
var readResponse = Read(client, id);

var returnedObj = GetString(readResponse);
readResponse = Read(client, id);

var rev1 = GetString("_rev", readResponse);
var updateResponse = Update(client, id, new { name = "john", age = 36, _rev = rev1 });

var rev2 = GetString("rev", updateResponse);
var deleteResponse = Delete(client, id, rev2);

#endregion manage simple json document

The code below demonstrates how you can manage CRUD operations with data from sensors. We are assuming that a similar class will be used in the next tutorials for our IoT solution.

#region manage data from sensors

//unfinite loop until esc key is pressed
Console.WriteLine("Press ESC to stop");
    while (!Console.KeyAvailable)

        Sensor sensor = Sensor.Generate();
        var creationSensorResponse = Create(client, sensor);

        var _id = GetString("id", creationSensorResponse);
        var readSensorResponse = Read(client, _id);

        var returnedSensorObj = GetString(readSensorResponse);

        readSensorResponse = Read(client, _id);
        rev1 = GetString("_rev", readSensorResponse);
        var updateSensorResponse = Update(client, _id, new { time = sensor.time, dspl = sensor.dspl, temp = sensor.temp, hmdt = sensor.hmdt, _rev = rev1 });
} while (Console.ReadKey(true).Key != ConsoleKey.Escape);

#endregion manage data from sensors

Basic CRUD helper classes: "Create", "Read", "Update" and "Delete" are shown below.

"Create" helper method.

#region Create
private static HttpResponseMessage Create(HttpClient client, object doc)
    var json = JsonConvert.SerializeObject(doc, Formatting.None);
    return client.PostAsync("", new StringContent(json, Encoding.UTF8, "application/json")).Result;
#endregion Create

"Read" helper method.

#region Read
private static HttpResponseMessage Read(HttpClient client, string id)
    return client.GetAsync(id).Result;
#endregion Read

"Update" helper method.

#region Update
private static HttpResponseMessage Update(HttpClient client, string id, object doc)
    var json = JsonConvert.SerializeObject(doc, Formatting.None);
    return client.PutAsync(id, new StringContent(json, Encoding.UTF8, "application/json")).Result;
#endregion Update

"Delete" helper method.

#region Delete
private static HttpResponseMessage Delete(HttpClient client, string id, string rev)
    return client.DeleteAsync(id + "?rev=" + rev).Result;
#endregion Delete

The console application is demonstrated on the picture below.

Helper methods are used to print the HttpResponseMessage and the whole JSON document.

Image 8

You can select the database via the Cloudant Management Portal and browse or query the documents

Image 9

Selecting a specific document you can see the full content of the JSON document.

Image 10


This tutorial is on how to start with IBM Cloudant, how to create an account, manage databases and implement via C# and .NET a simple client that can manage CRUD operations via REST interface.

The next part will be more focused on the Cloudant HTTP API. We will consider how to use this API to implement a simple IoT solution.


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Written By
Architect Strypes
Bulgaria Bulgaria
Mihail Mateev is a Technical Consultant, Community enthusiast, PASS RM for CEE and chapter lead, Microsoft Azure MVP
He works as Solutions Architect, Technical PM and Senior Technical Evangelist at Strypes
Mihail Mateev has experience as a Senior Technical Evangelist, Team Lead at Infragistics Inc. He worked as a Software developer and team lead on WPF and Silverlight Line of Business production lines of the company.
Mihail worked in various areas related to technology Microsoft: Silverlight, WPF, Windows Phone 7, Visual Studio LightSwitch, WCF RIA Services, ASP.Net MVC, Windows Metro Applications, MS SQL Server and Windows Azure. He also write many jQuery related blogs.
Over the past ten years, Mihail has written articles for Bulgarian Computer World magazine, blogs about .Net technologies. He is a contributor and a technical editor of publications PACKT Publishing and Wiley. Mihail did presentations for .Net and Silverlight user groups in Bulgaria. He has an Experience with GIS system over .Net framework. He worked more than five years in ESRI Bulgaria like a Software developer and a trainer. Several years Mihail did a lectures about Geographic Information Systems in the Sofia University “St. Kliment Ohridski” , Faculty of Mathematics and Informatics. Mihail is also a lecturer about Computer Systems in the University of the Architecture, Civil Engineering and Geodesy in Sofia at Computer Aided Engineering Department. Mihail holds master's degrees in Structural Engineering and Applied Mathematics and Informatics.

Comments and Discussions

-- There are no messages in this forum --