Choosing a Cloudant Library
Which level of abstraction is “just right” for you?
The beauty of Apache CouchDB and Cloudant is that you don’t need to a library to be able to start using it. Some databases require a “driver” module to be installed to handle communication between your application and your database, but when your database speaks HTTP then you only need curl, a web browser, or anything that can make web requests. For example:
- your Raspberry Pi could write IoT data to a remote database by making PUT requests from curl
- your web page could fetch data directly from the database by making in-page HTTP calls
- your PHP code could read and write from its data store without any third-party add-on code
Sometimes developers need a little help. To avoid repeating the same low-level code, to abstract the API calls into more semantically meaningful methods, and to make life easier we often employ libraries.
In this article we’ll explore some options that a JavaScript/Node.js developer could choose when writing code against CouchDB or Cloudant, from the lowest level to the highest. (The following code snippets show fetching all documents from a Cloudant database.)
Level 0 — no libraries
If you want to learn the HTTP in detail, then you can choose to use no libraries whatsoever:
This approach uses the Node.js https library to make a single API call. It leaves you to formulate your own URL and to join the separate chunks of reply data into a complete JSON response.
Level 1 — an HTTP request library
To help with formulating HTTP requests, there a several third-party HTTP libraries to choose from. I usually go for request, but others are available.
The request module makes it simpler to deal with HTTP requests, and if you ask it nicely, it will parse the JSON response for you too. You still get to learn the CouchDB API, but the mechanics of making the HTTP call are simplified.
Level 2 — the Nano library
Nano is an open-source project that was donated to the Apache Software Foundation and has become the official Node.js library for CouchDB.
It doesn’t actually do much — it is a thin wrapper around CouchDB’s API — but it does make your code a little easier to write and to maintain:
Using Nano allows you to abstract the API calls away. In this case, the list function makes a GET /db/_all_docs API call. You can use the Nano library and not know what API calls are being made on your behalf.
Level 3 — the Cloudant library
The Cloudant library extends Nano to add:
- functions that wrap Cloudant-specific API calls
- a plugin system to allow Promises, retry logic and cookie authentication wrappers to be used
- official support from IBM Cloudant (it’s the only supported Node.js Cloudant library in this article)
Here’s how you could use Promises instead of callbacks:
Some of the plugins make multiple API calls for one function call (e.g., swap your Cloudant credentials for a token), then make a second API call to fetch the data you need passing the token. You don’t see the individual API calls, just the response.
Level 4 — PouchDB
You can use PouchDB as an HTTP-only client too:
It has its own naming convention for functions, but function calls result in the equivalent API call. If you’re developing with PouchDB on the client side, it may be easier to stick with the same API to deal with your server-side CouchDB or Cloudant database.
Level 5 — the silverlining library
The silverlining library builds on the request library, not on Nano. It provides a different abstraction from the Cloudant API, hiding some of the complexities that confuse first-time users and providing higher-level simplifications.
The data returned by silverlining doesn’t necessarily match the data from the Cloudant API. It tidies up and simplifies returned data, removing revision tokens and complicated scaffolding.
It also abstracts the creation of indicies, which means that performing an aggregation on a data set no longer requires users to understand the CouchDB MapReduce system:
Alternatives
The great thing about open-source is that you aren’t limited to “official” products. If you don’t like the tools, help improve the open-source offerings by raising issues or submitting code — find alternative tools or build your own! You can choose whether you’re looking for a library that can do callbacks or Promises and whether it allows you to learn the CouchDB API or hides it from you.
In my opinion, it makes sense to get started with a high-level library that abstracts and hides details from you at first. It allows you to build more quickly with less distraction. As you get more serious in your work, you may find you need to see more detail and switch to a lower-level of abstraction.
If you enjoyed this article, please ♡ it to recommend it to other Medium readers.
