CouchDB HTTP API and Mono

NOTE: Tested on CouchDB 1.0

I finally got around to work a bit more with CouchDB, that is a document-oriented database – the NoSQL you’ve probably heard about so much lately.

So I decided to experiment with it and since it offered a HTTP API, I decided to try it out with a Mono application on a Ubuntu box (hosted inside a virtual machine). It will surely work as a regular .NET application, so feel free to use the provided samples in Windows as well, but make sure that CouchDB is properly working there first.

Once you install CouchDB, you are able to access it via a web UI called Futon.

Via this interface it is fairly easy to create new databases and content, as well as manage the security settings and the space occupied by the stored data.

The exposed HTTP API allows users to perform several maintenance and management tasks from any application that is able to implement a REST interface.

To test this API, I created a simple Mono console application (C# - using MonoDevelop):

I added the references to System.Net (to work with HTTP requests and responses) and System.IO (to work with streams).

The first method I am going to implement is the one that gets information about all databases that are registered on the server. To be specific, this is the method that will list the existing databases. Here is how it looks like:

static void GetAllDatabases()
{
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://127.0.0.1:5984/_all_dbs");
    request.Method ="GET";
    
    using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
    {
        using (StreamReader reader = new StreamReader(response.GetResponseStream()))
        {
            Console.WriteLine(reader.ReadToEnd());
        }
    }    
}

If you worked with HTTP requests before, then there is nothing special in the method above. But look at the URL:

http://127.0.0.1:5984/_all_dbs

/_all_dbs is the way to call the function that will display all databases via a GET request. Once you build and run the application, you should see an output similar to this:

["test_db","_users"]

To create a database, a bit of a different approach is used. Here is the method in case:

static void CreateDatabase(string name)
{
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://127.0.0.1:5984/" + name.ToLower());
    request.Method ="PUT";
    
    using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
    {
        using (StreamReader reader = new StreamReader(response.GetResponseStream()))
        {
            Console.WriteLine(reader.ReadToEnd());
        }
    }    
}

First of all, the request method is PUT instead of GET. Then, as you can see, the URL format passed to the request follows this pattern:

http://127.0.0.1:5984/new_database_name

Notice however, that I am using name.ToLower() – this is because in CouchDB I cannot have databases named with uppercase letters. Also, the only special characters that are allowed are: _, $, (, ), +, -, and /

The database deletion is performed in a similar manner as the CreateDatabase method. All that changes is the method type for the request, which is DELETE.

static void DeleteDatabase(string name)
{
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://127.0.0.1:5984/" + name.ToLower());
    request.Method ="DELETE";
    using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
    {
        using (StreamReader reader = new StreamReader(response.GetResponseStream()))
        {
            Console.WriteLine(reader.ReadToEnd());
        }
    }    
}

Both for CreateDatabase and DeleteDatabase, the output for a successful operation should look like this:

{"ok":true}

Getting database information is also very similar, but it is using a GET request with the URL of the same pattern (http://127.0.0.1:5984/database_name).

static void GetDatabaseInfo(string name)
{
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create("http://127.0.0.1:5984/" + name.ToLower());
    request.Method ="GET";
    
    using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
    {
        using (StreamReader reader = new StreamReader(response.GetResponseStream()))
        {
            Console.WriteLine(reader.ReadToEnd());
        }
    }    
}

The output for the call should look like this (JSON-formatted):

{
"db_name":"test_db",
"doc_count":0,
"doc_del_count":0,
"update_seq":0,
"purge_seq":0,
"compact_running":false,
"disk_size":79,
"instance_start_time":"1279485090324739",
"disk_format_version":5
}

Although the API might seem a bit limited, it offers the basic functionality set that enables the developers to access the data on a CouchDB server from anywhere via a simple REST implementation.

Hopefully in the next CouchDB releases we will see a more extended API that will allow developers to manage the server and the data on it.

For more information on the CouchDB HTTP API, read here.