PUTting the Couch(DB) in Your Living Room

In my previous posts, I provided a shallow introduction to CouchDB and how to get it installed on a Linux box. Here are the links to these posts:

1. Relaxing on the Couch(DB)
2. Installing the Couch(DB)

Now, for this post I want to talk about how to create and manage documents. As I already mentioned in my introductory blog post, CouchDB is accessible through a RESTful HTTP/JSON API. This means that documents are stored as JSON objects. Let me show you an example of how to store a document in CouchDB. 

Suppose we have a class named Document (how creative of me). A Document has a title, an author and a collection of Tag objects. A Tag is a value object that has a name.

public class Document
{
    private readonly ISet<Tag> _tags;

    public String Author { get; }
    public String Title { get; }
    public Guid Id { get; }
    public String Version { get; }

    public IEnumerable<Tag> Tags
    {
        get { return _tags; }
    }
}

public class Tag : ValueObject<Tag>
{
    public String Name { get; private set; }

    public Tag(String name)
    {    
        Name = name;
        RegisterProperty(value => value.Name);
    }
} 

Nothing fancy so far. Now in order to save an instance of this class, we have to serialize it to its JSON representation. I’ve been using Json.NET for this purpose, but you might as well use the JavaScriptSerializer class from the .NET framework.

Now, in order to save a document, we make use of the PUT HTTP method. This implies that we have to provide our own document identifier. We have to initialize the Id property with a new GUID for a new Document. We could also make use the POST HTTP method. This way you don’t have to specify your own document identifier and let CouchDB generate one for you when the document is initially stored. But this is discouraged because proxies and other network intermediaries are able to resend POST requests resulting in duplicate documents.

Creating a new document in CouchDB using the PUT method takes the following general form:

http://myhost:5984/my_database/my_id

So for our example, sending the following request:

PUT /documentstore/80c8675d-2015-45f5-a3c7-098226e15ce3 HTTP/1.1
Content-Type: application/json
Host: 146.135.16.100:5984
Content-Length: 1215256
Expect: 100-continue

{
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"}]
}

makes CouchDB return the following response:

{
"ok":true,
"id":"80c8675d-2015-45f5-a3c7-098226e15ce3",
"rev":"1-1437623276"
}

You probably figured out by now that this response means that the document has successfully been stored by CouchDB. Notice that it also returns a revision number that was generated upon creating the document in the database. This is important when we try to save changes to the document later on.

If you’re as suspicious as I am, you probably want to verify whether CouchDB  correctly stored the document we’ve provided. You can do this using Futon, the web-based user interface of CouchDB. You can access Futon through the following URL:

http://myhost:5984/_utils

Say that we already want to make some changes to the document we just created. Lets add a new tag to the document named ‘Space’. We add a new Tag object to the instance of our Document, we serialize it back to its JSON representation and send the following request, asking CouchDB to save the changes:

PUT /documentstore/80c8675d-2015-45f5-a3c7-098226e15ce3 HTTP/1.1
Content-Type: application/json
Host: 146.135.16.100:5984
Content-Length: 1705803
Expect: 100-continue

{
"_rev":"1-1437623276",
"Author":"Stephen Hawking",
"Title":"The Universe in a Nutshell",
"Tags":[{"Name":"Physics"},{"Name":"Universe"},{"Name":"Space"}]
}

Notice that we are using the PUT method again, but now we also provided the revision number we got back from our first response when we initially created the document. Also notice that we are sending the complete document again, but now with the extra tag.

CouchDB returns the following response that contains a new revision number for the document:

{
"ok":true,
"id":"80c8675d-2015-45f5-a3c7-098226e15ce3",
"rev":"2-3213552600"
}

Again, you can use Futon to verify if CouchDB stored a new version of the document. For my next post on CouchDB, I will talk about how retrieve a document from CouchDB.