@ibm-cloud/cloudant
Advanced tools
Node.js client library to interact with various Cloudant APIs.
Disclaimer: this SDK is being released initially as a pre-release version. Changes might occur which impact applications that use this SDK.
The IBM Cloudant Node.js SDK allows developers to programmatically interact with Cloudant.
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 for them: develop.
Reasons why you should consider using Cloudant SDK for Node.js in your project:
Promise based design with asynchronous HTTP requests.npm install @ibm-cloud/cloudant
This library requires some of your Cloudant service credentials to authenticate with your account.
IAM, COUCHDB_SESSION, BASIC or NOAUTH authentication type.
apikey instead of a user-given password.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.username and password credentials.urlYou have to add these properties as your environment variables, because some examples that follow assume that these variables are set. To learn more about authentication configuration see the related documentation in the Cloudant API docs or in the general SDK usage information.
For Cloudant IAM authentication set the following environmental variables by replacing <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>
For COUCHDB_SESSION authentication set the following environmental variables by replacing <url>, <username> and <password> with your proper service credentials.
CLOUDANT_AUTH_TYPE=COUCHDB_SESSION
CLOUDANT_URL=<url>
CLOUDANT_USERNAME=<username>
CLOUDANT_PASSWORD=<password>
For Basic authentication set the following environmental variables by replacing <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 using IAM for Cloudant and Session for CouchDB authentication.
This example code gathers some information about an existing database hosted on the https://examples.cloudant.com
service url.
To do this, you need to extend your environment variables with the service url and authentication type to use
NOAUTH authentication while reaching 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.
EXAMPLES_URL=https://examples.cloudant.com
EXAMPLES_AUTH_TYPE=NOAUTH
Once the environment variables are set, you can try out the code examples.
// 1. Create a Cloudant client with "EXAMPLES" service name ===================
const examplesClient =
CloudantV1.newInstance({serviceName:"EXAMPLES"});
// 2. Get server information ==================================================
// call service without parameters:
examplesClient.getServerInformation()
.then(serverInformation => {
const version = serverInformation.result.version;
console.log(`Server version ${version}`);
});
// 3. Get database information for "animaldb" =================================
const dbName = "animaldb";
// call service with embedded parameters:
examplesClient.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:
examplesClient.getDocument(getDocParams)
.then(documentAboutZebra => {
// result object is defined as a Document here:
const result: CloudantV1.Document = documentAboutZebra.result;
console.log("Document retrieved from database:\n" +
JSON.stringify(result, null, 2));
});
const getInfoFromExistingDatabase = async () => {
// 1. Create a Cloudant client with "EXAMPLES" service name ===================
const examplesClient = CloudantV1.newInstance({ serviceName: 'EXAMPLES' });
// 2. Get server information ==================================================
// call service without parameters:
const version = (await examplesClient.getServerInformation()).result.version;
console.log(`Server version ${version}`);
// 3. Get database information for "animaldb" =================================
const dbName = 'animaldb';
// call service with embedded parameters:
const dbInfo = await examplesClient.getDatabaseInformation({ db: dbName });
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 = { db: dbName, docId: 'zebra' };
// call service with predefined parameters:
const documentAboutZebra = await examplesClient.getDocument(getDocParams);
// result object is defined as a Document here:
const result = documentAboutZebra.result;
console.log('Document retrieved from database:\n' + JSON.stringify(result, null, 2));
};
if (require.main === module) {
getInfoFromExistingDatabase();
}
The result of the code is similar to the following output. The order of the output lines may change due to the asynchronicity.
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"
}
Now comes the exciting part of creating your own orders database and adding a document
about Bob Smith with your own IAM or Basic service credentials.
interface OrderDocument extends CloudantV1.Document {
name?: string;
joined?: string;
_id: string;
_rev?: string;
}
// 1. Create a client with `CLOUDANT` default service name ================
const client = CloudantV1.newInstance({});
// 2. Create a database =======================================================
const exampleDbName = "orders";
// Try to create database if it doesn't exist
const createDb = client.putDatabase({db: exampleDbName})
.then(putDatabaseResult => {
if (putDatabaseResult.result.ok) {
console.log(`"${exampleDbName}" database created."`);
}
})
.catch(err => {
if (err.code === 412){
console.log("Cannot create \"" + exampleDbName +
"\" database, it already exists.");
}
});
// 3. Create a document =======================================================
// Create a document object with "example" id
const exampleDocId = "example";
// set required _id property on exampleDocument:
const exampleDocument: OrderDocument = {_id: exampleDocId};
// Add "name" and "joined" fields to the document
exampleDocument.name = "Bob Smith";
exampleDocument.joined = "2019-01-24T10:42:99.000Z";
/* Try to get the document and set revision of exampleDocument to the
latest one if it previously existed in the database */
createDb.then(() => {
client.getDocument({db: exampleDbName, docId: exampleDocId})
.then(documentInfo => {
exampleDocument._rev = documentInfo.result._rev;
console.log("The document revision for" + exampleDocId +
"is set to " + exampleDocument._rev);
})
.catch(err => {
if (err.code === 404) {
// Document does not exist in database
}
})
.finally(() => {
// Save the document in the database
client.postDocument({
db: exampleDbName,
document: exampleDocument
}
).then(createDocumentResponse => {
// Keep track with the revision number of the document object
exampleDocument._rev = createDocumentResponse.result.rev;
console.log("You have created the document:\n" +
JSON.stringify(exampleDocument, null, 2));
});
});
});
const createDbAndDoc = async () => {
// 1. Create a client with `CLOUDANT` default service name ================
const client = CloudantV1.newInstance({});
// 2. Create a database =======================================================
const exampleDbName = 'orders';
// Try to create database if it doesn't exist
try {
const putDatabaseResult = (
await client.putDatabase({
db: exampleDbName,
})
).result;
if (putDatabaseResult.ok) {
console.log(`"${exampleDbName}" database created.`);
}
} catch (err) {
if (err.code === 412) {
console.log('Cannot create "' + exampleDbName + '" database, it already exists.');
}
}
// 3. Create a document =======================================================
// Create a document object with "example" id
const exampleDocId = 'example';
const exampleDocument = { _id: exampleDocId };
// Add "name" and "joined" fields to the document
exampleDocument['name'] = 'Bob Smith';
exampleDocument.joined = '2019-01-24T10:42:99.000Z';
/* Try to get the document and set revision of exampleDocument to the
latest one if it previously existed in the database */
try {
exampleDocument._rev = (
await client.getDocument({
db: exampleDbName,
docId: exampleDocId,
})
).result._rev;
console.log(
'The document revision for "' + exampleDocId + '" is set to ' + exampleDocument._rev
);
} catch (err) {
if (err.code === 404) {
// Document does not exist in database
}
} finally {
// Save the document in the database
const createDocumentResponse = await client.postDocument({
db: exampleDbName,
document: exampleDocument,
});
// Keep track with the revision number of the document object
exampleDocument._rev = createDocumentResponse.result.rev;
console.log('You have created the document:\n' + JSON.stringify(exampleDocument, null, 2));
}
};
if (require.main === module) {
createDbAndDoc();
}
The result of the code is similar to the following output. The order of the output lines may change due to the asynchronicity.
"orders" database created.
You have created the document:
{
"_id": "example",
"name": "Bob Smith",
"joined": "2019-01-24T10:42:99.000Z",
"_rev": "1-1b403633540686aa32d013fda9041a5d"
}
Note: this example code assumes that you have created both the orders database and the example
document by running this previous example code
successfully, otherwise you get the Cannot update document because either "orders" database or "example" document was not found. message.
interface OrderDocument extends CloudantV1.Document {
address?: string;
joined?: string;
_id?: string;
_rev?: string;
}
// 1. Create a client with `CLOUDANT` default service name ================
const client = CloudantV1.newInstance({});
// 2. Update the document =====================================================
// Set the options to get the document out of the database if it exists
const exampleDbName = "orders";
// Try to get the document if it previously existed in the database
const getDocParams: CloudantV1.GetDocumentParams =
{docId: "example", db: exampleDbName};
client.getDocument(getDocParams)
.then(docResult => {
// using OrderDocument on getDocument result:
const document: OrderDocument = docResult.result;
// Add Bob Smith's address to the document
document.address = "19 Front Street, Darlington, DL5 1TY";
// Remove the joined property from document object
delete document.joined;
// Update the document in the database
client.postDocument({db: exampleDbName, document})
.then(res => {
// Keeping track with the revision number of the document object:
document._rev = res.result.rev;
console.log("You have updated the document:\n" +
JSON.stringify(document, null, 2));
});
})
.catch(err => {
if (err.code === 404) {
console.log(
"Cannot update document because either \"" +
exampleDbName + "\" database or the \"example\" " +
"document was not found."
);
}
});
const updateDoc = async () => {
// 1. Create a client with `CLOUDANT` default service name ================
const client = CloudantV1.newInstance({});
// 2. Update the document =====================================================
// Set the options to get the document out of the database if it exists
const exampleDbName = 'orders';
// Try to get the document if it previously existed in the database
try {
const document = (
await client.getDocument({
docId: 'example',
db: exampleDbName,
})
).result;
// Add Bob Smith's address to the document
document.address = '19 Front Street, Darlington, DL5 1TY';
// Remove the joined property from document object
delete document['joined'];
// Keeping track with the revision number of the document object:
document._rev = (
await client.postDocument({
db: exampleDbName,
document: document,
})
).result.rev;
console.log('You have updated the document:\n' + JSON.stringify(document, null, 2));
} catch (err) {
if (err.code === 404) {
console.log(
'Cannot update document because either "' +
exampleDbName +
'" database or the "example" ' +
'document was not found.'
);
}
}
};
if (require.main === module) {
updateDoc();
}
The result of the code is similar to the following output.
You have updated the document:
{
"_id": "example",
"_rev": "2-70476cf75eb02f55c6c4061aa6941ec8",
"name": "Bob Smith",
"address": "19 Front Street, Darlington, DL5 1TY"
}
Note: this example code assumes that you have created both the orders database and the example
document by running this previous example code
successfully, otherwise you get the Cannot delete document because either "orders" database or "example" document was not found. message.
interface OrderDocument extends CloudantV1.Document {
name?: string;
address?: string;
joined?: string;
_id?: string;
_rev?: string;
}
// 1. Create a client with `CLOUDANT` default service name ================
const client = CloudantV1.newInstance({});
// 2. Delete the document =============================================
// Set the options to get the document out of the database if it exists
const exampleDbName = "orders";
const exampleDocId = "example";
// Try to get the document if it previously existed in the database
const getDocParams: CloudantV1.GetDocumentParams =
{docId: exampleDocId, db: exampleDbName};
client.getDocument(getDocParams)
.then(docResult => {
const document: OrderDocument = docResult.result;
client.deleteDocument({
db: exampleDbName,
docId: document._id,
rev: document._rev}).then(() => {
console.log("You have deleted the document.");
});
})
.catch(err => {
if (err.code === 404) {
console.log(
"Cannot delete document because either \"" +
exampleDbName + "\" database or the \"example\" " +
"document was not found."
);
}
});
const deleteDoc = async () => {
// 1. Create a client with `CLOUDANT` default service name ================
const client = CloudantV1.newInstance({});
// 2. Delete the document =============================================
// Set the options to get the document out of the database if it exists
const exampleDbName = 'orders';
const exampleDocId = 'example';
// Try to get the document if it previously existed in the database
try {
const document = (
await client.getDocument({
docId: exampleDocId,
db: exampleDbName,
})
).result;
await client.deleteDocument({
db: exampleDbName,
docId: document._id,
rev: document._rev,
});
console.log('You have deleted the document.');
} catch (err) {
if (err.code === 404) {
console.log(
'Cannot delete document because either "' +
exampleDbName +
'" database or the "example" ' +
'document was not found.'
);
}
}
};
if (require.main === module) {
deleteDoc();
}
The result of the code is the following output.
You have deleted the document.
For general SDK usage information, please see this link
If you are having difficulties using this SDK or have a question about the IBM Cloud services, please ask a question at Stack Overflow.
If you encounter an issue with the SDK, you are welcome to submit a bug report. Before that, please search for similar issues. It's possible someone has already encountered this issue.
Find more open source projects on the IBM Github Page
See CONTRIBUTING.
This project is released under the Apache 2.0 license. The license's full text can be found in LICENSE.
FAQs
IBM Cloudant Node.js SDK
The npm package @ibm-cloud/cloudant receives a total of 18,220 weekly downloads. As such, @ibm-cloud/cloudant popularity was classified as popular.
We found that @ibm-cloud/cloudant demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket detected a malicious Python package impersonating a popular browser cookie library to steal passwords, screenshots, webcam images, and Discord tokens.
Security News
Deno 2.0 is now available with enhanced package management, full Node.js and npm compatibility, improved performance, and support for major JavaScript frameworks.
Security News
The Internet Archive's "Wayback Machine" has been hacked and defaced, with 31 millions records compromised.