(untagged)

Getting Started with Cloudant

Mihail Mateev

9 Jun 2016

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.

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.

Background

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.

Prerequisites

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 https://cloudant.com/. 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.

<img height="584px" src="1105449/image004.png" width="640px" />

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: https://www.visualstudio.com/en-us/products/visual-studio-community-vs.aspx

And finally, you will need a Microsoft Azure account. You can create a free trial here: https://azure.microsoft.com/en-us/free/

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.

<img height="362px" src="1105449/image005.png" width="640px" />

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.

<img height="362px" src="1105449/image006.png" width="640px" />

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.

<img height="362px" src="1105449/image007.png" width="640px" />

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

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}.cloudant.com/{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 });
PrintResponse(creationResponse);

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

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

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

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

#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");
do
{
    while (!Console.KeyAvailable)
    {

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

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

        var returnedSensorObj = GetString(readSensorResponse);
        PrintDocument(returnedSensorObj);

        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 });
        PrintResponse(updateSensorResponse);
    }
} 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.

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

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

Summary

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.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here