This module demonstrates how JSON documents may be stored, retrieved and updated using JavaScript. For this the Firefox scratchpad is used. However the code snippets provided may be easily adapted for other purposes.

What is a JSON document?

JSON means JavaScript Object Notation. It is used to describe data objects. More on this in the module JavaScript Object Notation.

We take an example document from that module:

var myDict = {};  // create a new instance of Object

myDict["red"] = "rot";
myDict["blue"] = "blau";
myDict["yellow"] = "gelb";
myDict["green"] = "grün";
myDict["white"] = "weiss";
myDict["brown"] = "braun";
myDict["black"] = "schwarz";


JSON.stringify(myDict, undefined, 4)/*

{
    "red": "rot",
    "blue": "blau",
    "yellow": "gelb",
    "green": "grün",
    "white": "weiss",
    "brown": "braun",
    "black": "schwarz"
}
*/

Document identification

Each document in a couchDB database instance needs an identification. It can be anything but must be unique in the database. Often GUIDs (or UUIDs) are used.

Document revision number

couchDB assigns a document revision number to each document. Old versions are kept. The attribute name used is _rev.

PUT

By using the Http PUT request with an identification a JSON object may be stored for the first time in a database. Here colorDictionary is used as identification.

// prepare request
   var req = new XMLHttpRequest();
   req.open("PUT", "../colorDictionary", false);  // request type, URL, asynchronous = false
   var mimeType="application/json";
   req.setRequestHeader('Content-Type', mimeType); 
   
   console.log("Object to put in couchDB");   // print out the object on the console
   console.log(JSON.stringify(myDict, undefined, 4));  // use pretty printing   
   
   req.send(JSON.stringify(myDict));  // send the JavaScript object as a string.

As the answer to the request couchDB gives buck a responseText. It contains the string version of a result JSON object. If the storing operation was successful that object has an attribute "ok" which is then true.

The same code as above without comments and relying on default values for the mime type. The identification used here is "colorDictionary2".

   var req = new XMLHttpRequest();
   req.open("PUT", "../colorDictionary2", false);  
   req.send(JSON.stringify(myDict)); 

POST without a key

When you do not want to provide an identification value for the JSON object to be stored you need to use the Http POST request. The couchDB instance will then automatically assign an identification key.

var req = new XMLHttpRequest();
   req.open("POST", "../", false);  
   req.setRequestHeader('Content-Type', "application/json"); 
   req.send(JSON.stringify(myObj)); 
   

The http GET command is used.

var url="../colorDictionary";

var request = new XMLHttpRequest();

request.open("GET", url, false);   //  asynchronous = false

request.send(null);

request.responseText

Asynchronous operation

In this module the document was stored in synchronous mode. Normally people use the asynchronous mode. A module which shows that is in preparation.

Updating a document

To update a document the document has to be retrieved first, the attributes updated and then stored again. Module with the example above is in preparation.