IBM Cloudant Node.js SDK Version 0.1.2

IBM Cloudant Node.js SDK is a client library that interacts with the IBM Cloudant APIs.

Disclaimer: This library is still a 0.x release. We do consider this library production-ready and capable, but there are still some limitations we’re working to resolve, and refinements we want to deliver. We are working really hard to minimise the disruption from now until the 1.0 release, but there may still be some changes that impact applications using this SDK. For now, be sure to pin versions to avoid surprises.

Table of Contents

Overview

The IBM Cloudant Node.js SDK allows developers to programmatically interact with IBM Cloudant with the help of the @ibm-cloud/cloudant package.

Features

The purpose of this Node.js SDK is to wrap most of the HTTP request APIs provided by Cloudant and supply other functions to ease the usage of Cloudant. This SDK should make life easier for programmers to do what’s really important to them: developing software.

Reasons why you should consider using Cloudant Node.js SDK in your project:

• Supported by IBM Cloudant.
• Server compatibility with:
  • IBM Cloudant "Classic".
  • Cloudant "Standard on Transaction Engine" for APIs compatible with Cloudant "Classic". For more information, see the Feature Parity page.
  • Apache CouchDB 3.x for data operations.
• Includes all the most popular and latest supported endpoints for applications.
• Handles the authentication.
• Familiar user experience with IBM Cloud SDKs.
• Flexibility to use either built-in models or byte-based requests and responses for documents.
• Promise based design with asynchronous HTTP requests.
• Use either as native JavaScript or take advantage of TypeScript models.
• Transparently compresses request and response bodies.

Prerequisites

• A Cloudant service instance or a CouchDB server.
• Node.js 14 or 16.

Installation

npm install @ibm-cloud/cloudant

Authentication

This library requires some of your Cloudant service credentials to authenticate with your account.

1. IAM, COUCHDB_SESSION, BASIC or NOAUTH authentication type.
   1. IAM authentication is highly recommended when your back-end database server is Cloudant. This authentication type requires a server-generated apikey instead of a user-given password. You can create one here.
   2. Session cookie (COUCHDB_SESSION) authentication is recommended for Apache CouchDB or for Cloudant when IAM is unavailable. It exchanges username and password credentials for an AuthSession cookie from the /_session endpoint.
   3. Basic (or legacy) authentication is a fallback for both Cloudant and Apache CouchDB back-end database servers. This authentication type requires the good old username and password credentials.
   4. Noauth authentication does not require credentials. Note that this authentication type only works with queries against a database with read access for everyone.
2. The service url.

There are several ways to set these properties:

Authentication with environment variables

IAM authentication

For Cloudant IAM authentication, set the following environmental variables by replacing the <url> and <apikey> with your proper service credentials. There is no need to set CLOUDANT_AUTH_TYPE to IAM because it is the default.

CLOUDANT_URL=<url>
CLOUDANT_APIKEY=<apikey>

Session cookie authentication

For COUCHDB_SESSION authentication, set the following environmental variables by replacing the <url>, <username> and <password> with your proper service credentials.

CLOUDANT_AUTH_TYPE=COUCHDB_SESSION
CLOUDANT_URL=<url>
CLOUDANT_USERNAME=<username>
CLOUDANT_PASSWORD=<password>

Basic authentication

For Basic authentication, set the following environmental variables by replacing the <url>, <username> and <password> with your proper service credentials.

CLOUDANT_AUTH_TYPE=BASIC
CLOUDANT_URL=<url>
CLOUDANT_USERNAME=<username>
CLOUDANT_PASSWORD=<password>

Note: We recommend that you use IAM for Cloudant and Session for CouchDB authentication.

Authentication with external configuration

To use an external configuration file, the Cloudant API docs, or the general SDK usage information will guide you.

Programmatic authentication

To learn more about how to use programmatic authentication, see the related documentation in the Cloudant API docs or in the Node.js SDK Core document about authentication.

Using the SDK

For fundamental SDK usage information and config options, please see the common IBM Cloud SDK documentation.

Request timeout configuration

No request timeout is defined, but a 2.5m connect and 2.5m read timeout is set by default. Be sure to set a request timeout appropriate to your application usage and environment. The request timeout section contains details on how to change the value.

Note: System settings may take precedence over configured timeout values.

Code examples

The following code examples authenticate with the environment variables.

1. Retrieve information from an existing database

Note: This example code assumes that animaldb database does not exist in your account.

This example code gathers information about an existing database hosted on the https://examples.cloudant.com/ service url. To connect, you must extend your environment variables with the service url and authentication type to use NOAUTH authentication while you connect to the animaldb database. This step is necessary for the SDK to distinguish the EXAMPLES custom service name from the default service name which is CLOUDANT.

Cloudant environment variable naming starts with a service name prefix that identifies your service. By default this is CLOUDANT, see the settings in the authentication with environment variables section.

If you would like to rename your Cloudant service from CLOUDANT, you must use your defined service name as the prefix for all Cloudant related environment variables. The code block below provides an example of instantiating a user-defined EXAMPLES service name.

EXAMPLES_URL=https://examples.cloudant.com
EXAMPLES_AUTH_TYPE=NOAUTH

Once the environment variables are set, you can try out the code examples.

TypeScript:

import {CloudantV1} from "@ibm-cloud/cloudant";

// 1. Create a Cloudant client with "EXAMPLES" service name =====================
const client = CloudantV1.newInstance({ serviceName: 'EXAMPLES' });

// 2. Get server information ====================================================
// call service without parameters:
client.getServerInformation().then((serverInformation) => {
  const { version } = serverInformation.result;
  console.log(`Server version ${version}`);
});

// 3. Get database information for "animaldb" ===================================
const dbName = 'animaldb';

// call service with embedded parameters:
client.getDatabaseInformation({ db: dbName }).then((dbInfo) => {
  const documentCount = dbInfo.result.doc_count;
  const dbNameResult = dbInfo.result.db_name;

  // 4. Show document count in database =========================================
  console.log(
    `Document count in "${dbNameResult}" database is ${documentCount}.`
  );
});

// 5. Get zebra document out of the database by document id =====================
const getDocParams: CloudantV1.GetDocumentParams = {
  db: dbName,
  docId: 'zebra',
};

// call service with predefined parameters:
client.getDocument(getDocParams).then((documentAboutZebra) => {
  // result object is defined as a Document here:
  const { result } = documentAboutZebra;
  console.log(
    `Document retrieved from database:\n${JSON.stringify(result, null, 2)}`
  );
});

JavaScript:

  CloudantV1   

      
  
      :  

  
  
    version    
  

  
     

  
       :  
     
     

  
  
    
  

  
      :  :  

  
      

  
    result   

  
    
  


    
  

When you run the code, you see a result similar to the following output.

Server version 2.1.1
Document count in "animaldb" database is 11.
Document retrieved from database:
{
  "_id": "zebra",
  "_rev": "3-750dac460a6cc41e6999f8943b8e603e",
  "wiki_page": "http://en.wikipedia.org/wiki/Plains_zebra",
  "min_length": 2,
  "max_length": 2.5,
  "min_weight": 175,
  "max_weight": 387,
  "class": "mammal",
  "diet": "herbivore"
}

2. Create your own database and add a document

Note: This example code assumes that orders database does not exist in your account.

Now comes the exciting part, you create your own orders database and add a document about Bob Smith with your own IAM or Basic service credentials.

Create code exampleTypeScript:

    
  ?: 
  ?: 
  : 
  ?: 



   


   


   
   :  
    
      
      
    
  
    
        
      
        
      
    
  



   



 :    :  


  
  


  
  
    
      : 
      : 
    
    
    
    
    






    
      
      
      
        
      
         
            
      
    

JavaScript:

  CloudantV1   

      
  
     

  
     

  
   
       
       
        : 
      
    
      
      
    
     
        
      
        
      
    
  

  
  
     

  
  
      :  

  
    
    

  
      
    : 
    : 
  

  
  
  
  




  

  
  
    
  
     
        
  


    
  

When you run the code, you see a result similar to the following output.

"orders" database created.
You have created the document:
{
  "_id": "example",
  "name": "Bob Smith",
  "joined": "2019-01-24T10:42:59.000Z",
  "_rev": "1-1b403633540686aa32d013fda9041a5d"
}

3. Update your previously created document

Note: This example code assumes that you have created both the orders database and the example document by running the previous example code successfully. Otherwise, the following error message occurs, "Cannot update document because either 'orders' database or 'example' document was not found."

Update code exampleTypeScript:

    
  ?: 
  ?: 
  ?: 
  ?: 



   


   


 :   
  : 
  : 
















  
    
    
     :   

    
      

    
     

    
    
       :  document 
      
      
      
      
      
      

      
      
      
      
      







      
        
        
        
          
        
          
        
      
  
    
        
      
         
          
      
    
  

JavaScript:

  CloudantV1   

      
  
     
  
  
     

  
   
       
       
        : 
        : 
      
    

    
    
    







    

    
      

    
     

    
    
      
       
        : 
        document 
      
    

    
    
    







    

    
    
    
    
    









    

    
      
    
     
        
      
         
          
      
    
  


    
  

When you run the code, you see a result similar to the following output.

You have updated the document:
{
  "_id": "example",
  "_rev": "2-4e2178e85cffb32d38ba4e451f6ca376",
  "name": "Bob Smith",
  "address": "19 Front Street, Darlington, DL5 1TY"
}

4. Delete your previously created document

Note: This example code assumes that you have created both the orders database and the example document by running the previous example code successfully. Otherwise, the following error message occurs, "Cannot delete document because either 'orders' database or 'example' document was not found."

Delete code exampleTypeScript:

    
  ?: 
  ?: 
  ?: 
  ?: 
  ?: 



   



   
   


 :   
  : 
  : 



  
    
     :   

    
      
        : 
        :  
        :  
      
        
        
      
  
    
        
      
         
          
      
    
  

JavaScript:

  CloudantV1   

      
  
     

  
  
     
     

  
   
       
       
        : 
        : 
      
    

     
      : 
      :  
      :  
    
    
     
        
      
         
          
      
    
  


    
  

When you run the code, you see the following output.

You have deleted the document.

Error handling

For sample code on handling errors, see Cloudant API docs.

Raw IO

For endpoints that read or write document content it is possible to bypass usage of the built-in interface with byte streams.

Depending on the specific SDK operation it may be possible to:

• accept a user-provided byte stream to send to the server as a request body
• return a byte stream of the server response body to the user

Request byte stream can be supplied for NodeJS.ReadableStream or Buffer type parameters . For these cases you can pass this byte stream directly to the HTTP request body.

Response byte stream is supported in functions with the suffix of AsStream. The returned byte stream allows the response body to be consumed without triggering JSON unmarshalling that is typically performed by the SDK.

The update document section contains examples for both request and response byte stream cases.

The API reference contains further examples of using byte streams. They are titled "Example request as stream" and are initially collapsed. Expand them to see examples of:

Further resources

• Cloudant API docs: API reference including usage examples for Cloudant Node.js SDK API.
• TypeDoc: Cloudant Node.js SDK API Documentation.
• Cloudant docs: The official documentation page for Cloudant.
• Cloudant blog: Many useful articles about how to optimize Cloudant for common problems.

Questions

If you are having difficulties using this SDK or have a question about the IBM Cloud services, ask a question on Stack Overflow.

Issues

If you encounter an issue with the project, you are welcome to submit a bug report. Before you submit a bug report, search for similar issues and review the KNOWN_ISSUES file to verify that your issue hasn't been reported yet.

Open source at IBM

Find more open source projects on the IBM Github page.

Contributing

For more information, see CONTRIBUTING.

License

This SDK is released under the Apache 2.0 license. To read the full text of the license, see LICENSE.