Using the IBM Cloudant HTTP API Lab

If you do not already have the IBM Cloudant service provisioned in Bluemix, follow these steps to provision the service. ▼More

---

1. Visit IBM Bluemix at http://console.ng.bluemix.net.
2. If you don't have a Bluemix account, click Sign Up. Complete the fields on the form, and click Create Account.
3. If you have a Bluemix account, click Log In. Provide your IBMid and password, and click Log In.
4. In the top navigation bar, click Catalog.
5. In the left navigator, under Services, check Data and Analytics.
6. Click Cloudant NOSQL DB.
7. Accept the default service, or provide a different name, and click Create. This brings you to the IBM Cloudant Bluemix Service Launch Page.
8. Click Service Credentials. Note your username, password, and host name. You will be able to use the URL (which also passes your username and password) to access your database from a browser.
9. Paste the value for your username here:
10. Click this button to update the URLs for the rest of this tutorial.
11. Click Manage.
12. Click Launch to load the Cloudant dashboard.

---

As you walk through the tutorials on this page, you'll learn about some tools that help you work with the API. For a quick overview of these tools, watch this short video introduction. Each tutorial contains the links for installing each of the tools. ▼More

---

This short video shows you how to set up a pre-authenticated version of cURL so you don't need to supply your user credentials every time you issue a cURL command. ▼More

Watch this short video to see how to execute some basic create-read-update-delete commands using the API. ▼More

Try using cURL to access the Cloudant HTTP API and perform basic tasks. ▼More

---

Before you begin

The tutorial requires a unix shell, native on MacOS, and available through tools such as Cygwin on Windows.

cURL: You'll also need the cURL command line tool which you can download from here cURL . And set up pre-authenticated cURL as described here.

jq: You can optionally install jq which helps you by formatting the JSON response.

Cygwin: On Windows, you can install both cURL and jq as packages in Cygwin. Make sure the cygwin directory is included in the PATH environment variable.

Procedure 1: View account information

1. Open a command prompt in the Linux shell, and verify that you can run the cURL command by typing curl.
2. Get information about your account by running the following command.

   Command: acurl –X GET 'https://<account>.cloudant.com'
   Example output:

   
3. If you have jq installed, run the same command again, piping the output through jq to format the JSON response, and add the ‘-s’ flag to silence additional curl information in the output. ’–X GET’ is the default, so you do not have to include it for GET requests. The response should include the Cloudant build field along with a typical CouchDB response.

   Command: acurl -X GET 'https://<account>.cloudant.com' | jq .
   Example response:

   

Procedure 2: Getting a list of databases

5. Get a list of databases in your account using the ‘_all_dbs’ endpoint.

   Command: acurl 'https://<account>.cloudant.com/_all_dbs' | jq .
   Example response:

   

Procedure 3: Creating a database

6. Create a database called testdb using the PUT verb.

   Command: acurl –X PUT 'https://<account>.cloudant.com/testdb' Expected response:

   

Procedure 4: Using the Dashboard to Set Permissions

7. To change permissions on the newly created ‘testdb’ database to be world read and writeable to simplify the future tasks, go to the Cloudant Dashboard.
8. Open the testdb database.
9. Click Permissions.
10. Add Reader and Writer roles to Everybody Else as shown below.

    Example response:

    

Procedure 5: Creating a document

11. Create a document in the testdb database using the POST verb against the testdb endpoint. Omit the id, and thereby indicating that Cloudant should auto-generate a unique ID for the document. You must include a header for the Content-Type of application/json and use the –d parameter to pass the JSON document contents. The response should include “ok”: true along with the document _id and _rev.

    Command: acurl –X POST 'https://<account>.cloudant.com/testdb' –H 'Content-Type: application/json' –d '{"foo":bar"}' | jq .
    Example response:

    
12. Create a document in the testdb database using the PUT verb against the testdb/<DocID> endpoint. The custom endpoint that you define is used to create the document _id. The following example uses the _id ‘document1’.

    Command: acurl –X PUT 'https://<account>.cloudant.com/testdb/document1' –H 'Content-Type: application/json' –d '{"foo": "bar"}' | jq .
    Example response:

    

Procedure 6: View and delete documents

13. View all documents using the ‘_all_docs’ endpoint. This is also known as the Primary Index for a database. The response includes a key, which is the _id of the document in the case of the Primary Index, and a value, which is the latest _rev of the document in the case of the Primary Index.

    Command: acurl 'https://<account>.cloudant.com/testdb/_all_docs' | jq .
    Example response:

    
14. Delete the document that you just created. You need to specify both the document id and the latest rev of the document to delete it. Obtain the rev from the output of the previous step to get ‘_all_docs’.

    Command: acurl –X DELETE 'https://<account>.cloudant.com/testdb/document1?rev=<rev>' | jq .
    Example response:

    

---

Try working with the API through a browser. ▼More

---

Before you begin

Use either Chrome or Firefox for this tutorial and install the JSONView add-on for your browser. This tool lets you see JSON with syntax highlighting, which makes it easier to parse elements and read the code. Get it at:

• JSONView for Firefox
• JSONView for Chrome

Replicate the animaldb database from the http://education.cloudant.com account. If you need help creating the replication request, refer to the Replication video and Tutorial on the Create a Replication Job page.

Access API via browser

1. View your account information.
   URL: https://<account>.cloudant.com
   Example response
2. View all the databases in your account.
   URL: https://<account>.cloudant.com/_all_dbs
   Example response with JSONView enabled:
3. View all the documents in the animaldb database.
   URL: https://<account>.cloudant.com/animaldb/_all_docs
   Example response with JSONView enabled:
4. View the badger document in the animaldb database.
   URL: https://<account>.cloudant.com/animaldb/badger
   Example response with JSONView enabled:
5. View an image attached to a document. The document is in a database called crud in the ablanks account and has world-readable permissions.
   1. First, look at the document which indicates that there is an image attached to the document.
      URL: https://ablanks.cloudant.com/crud/welcome
      Example response with JSONView enabled:
   2. Next, view the attachment.
      URL: https://ablanks.cloudant.com/crud/welcome/ibm_cloudant_blue_x2.png
      Example response with JSONView enabled:

---

Try working with the API using a browser add-on tool. ▼More

---

Follow these steps using Chrome or Firefox.

1. Install one of the following tools. Both provide an easy user interface to manipulate the API, like sending requests to the Cloudant database, parsing a response, specifying a URL with credentials to authenticate, or adding headers. If you use:
   • Chrome, install POSTMan
   • Firefox, install RESTClient
2. If you haven't already done so, replicate the animaldb database from the http://education.cloudant.com account. If you need help creating the replication request, refer to the Replication video and Tutorial on the Create a Replication Job page.
3. Open either RESTClient or POSTMan, and view your account information.
   URL: https://<account>.cloudant.com
   Basic Authentication: Type your username and password. This information will be base64 encoded and passed in the header.
   Verb: GET
   Example responses in RESTClient and POSTMan:
4. View all the databases in your account.
   URL: https://<account>.cloudant.com/_all_dbs
   Verb: GET
   Example response in POSTMan:
5. View all the documents in the animaldb database.
   URL: https://<account>.cloudant.com/animaldb/_all_docs
   Verb: GET
   Example response in POSTMan:
6. View the leumur document in the animaldb database.
   URL: https://<account>.cloudant.com/animaldb/lemur
   Verb: GET
   Example response in POSTMan:
7. Create a new database called mynewdb.
   URL: https://<account>.cloudant.com/mynewdb
   Verb: PUT
   Example response in POSTMan:
8. Create a new document in the mynewdb database.
   URL: https://<account>.cloudant.com/mynewdb
   Verb: POST
   Raw JSON:
   {"name" : "William","age" : 50,"gender" : "male","_id" : "William"}
   Example response in POSTMan:
9. Create two documents in bulk in the mynewdb database.
   URL: https://<account>.cloudant.com/mynewdb/_bulk_docs
   Verb: POST
   Raw JSON: {"docs" : [{"name" : "Sarah","age" : 43,"gender" : "female","_id" : "sarah"},{"name" : "Nancy","age" : 51,"gender" : "female","_id" : "nancy"}]}
   Example response in POSTMan:
10. Delete a document in the mynewdb database. Obtain the revID for nancy from the previous reponse.
    URL: https://<account>.cloudant.com/mynewdb/nancy?rev=1-b0f9d52c0df68f99db4e05aed5033351
    Verb: DELETE
    Example response in POSTMan:

---

Find more videos and tutorials in the Learning Center.