Zero to Cloudant in 5 minutes

3 minute read


Creating an automatically updating news page

This is the first article in a series on how to use GitHub pages (the service that hosts this blog) and the BlueMix PaaS to create an automatically updating news section.

Persisting Data


I will be consuming the Cloudant Database as a Service to persist the articles I want for my news section of this blog. Cloudant DBaaS has several features that make it a good fit, including:

  • A JSON document database is a natural fit for storing news article information.
  • HTTP based API to update and access database
  • DBaaS - no servers to maintain, quick and easy setup

Getting started Cloudant on BlueMix

  1. Create a BlueMix account
  2. Find the Cloudant service
  3. Select a Cloudant plan
  4. Add Cloudant to your BlueMix

Create your BlueMix account

You will need to register to get started with BlueMix. Click here to create a BlueMix account.

Find the Cloudant Service

  • Select catalog from the top navigation bar
  • Check Data and Analytics on the filter on the left navigation bar.

You should see a screen like this

BlueMix Data Services
BlueMix Data Services

Select Cloudant NoSQL DB Service

Cloudant Service

Select Cloudant Plan

From here, you can add and configure the Cloudant service. I left all the default values and clicked create.

Select a Cloudant plan
Select a Cloudant Plan

Add Cloudant to your BlueMix

BlueMix will configure your Cloudant service. Once it is done click the Launch icon to open the Cloudant console.

Cloudant Launch

Refer to the BlueMix docs for more details or troubleshooting.

Setup Cloudant

Now that the Cloudant service is added, it needs to be configured for our use case.

Steps include:

  1. Create a DB
  2. Add a read only user
  3. Put our first news item in the database.

Create a Cloudant Database

Click on the upper right hand corner link that says create database. I named mine blog_news.

Create Database

Add a read only user

To access this from our the web browser I want to create a read only user ID.

To make and configure the user:

  • Select permissions from the left nav
  • Click Generate API key
  • Validate the new API key only has reader permissions.

When done your screen should look something like this

Create a Read-Only User
Create a read only user in Cloudant

Store the password for this user somewhere - you can’t retrieve it later.

Create a test news item

To create a test news item:

  • Navigate back to the All Documents section on the left Nav
  • Click the plus sign next to all documents
  • Select New Doc

Your screen should look like this right before you click ‘New Doc’ New Document

This should open the Cloudant online JSON text editor. Let’s author our first news item document. Add the following fields for all news article documents. In addition to the _id field inserted automatically by Cloudant we will

"title": "News Article",
"link": "",
"excerpt": "Summary of this article",
"timestamp": "1470844114"

Your screen should look something like this. New Document

Record the automatic document id assigned by Cloudant we will need that in the next section.

Click the create document button to insert the document into Cloudant.

Test Cloudant

To test our process we will retrieve the document we just inserted into Cloudant.

  1. Get the URL for the document
  2. Craft a curl to retrieve the document
  3. Validate document exists and matches what we submitted.

Get the URL for the document

In the all documents view, click on the pencil icon next to the document whose ID matches the document ID you noticed in the previous section. This should bring up an editable version of the document you crafted earlier. In the upper right hand side of the browser click the API icon and then select copy URL.

Your screen should look like this

Determine document URL
Determine the document URL

Create a curl like the one below replacing below with the key and password Cloudant generated for you earlier. The should be the one you just copied from the web interface.

Craft your curl

curl -u <key>:<password> <url>

This is what it looks like with some fake values in place.

curl -u icheteegesomenewh:ec4b7670b96ef1359c2d8342a6c

Compare documents

The results of the curl, should be the same JSON document you just finished creating with a revision id automatically inserted by Cloudant.

{ "_id":"aacf26fac49a1734f3a25cbc7fecfb02",
"title":"News Article",
"excerpt":"Summary of this article",


Should you run into any issues consult the BlueMix Documentation, the Cloudant Documentation or reach out to me on twitter