@ibm-cloud/cloudant
Advanced tools
@ibm-cloud/cloudant - npm Package Compare versions
Comparing version 0.0.10 to 0.0.11
| { | ||
| "name": "@ibm-cloud/cloudant", | ||
| "version": "0.0.10", | ||
| "version": "0.0.11", | ||
| "description": "IBM Cloudant Node.js SDK", | ||
@@ -42,3 +42,3 @@ "main": "index.js", | ||
| "extend": "^3.0.2", | ||
| "ibm-cloud-sdk-core": "^2.6.0" | ||
| "ibm-cloud-sdk-core": "~2.7.0" | ||
| }, | ||
@@ -45,0 +45,0 @@ "jest": { |
228
README.md
@@ -18,5 +18,6 @@ <!-- | ||
| # IBM Cloudant Node.js SDK Version 0.0.10 | ||
| # IBM Cloudant Node.js SDK Version 0.0.11 | ||
| Node.js client library to interact with various [Cloudant APIs](https://cloud.ibm.com/apidocs/cloudant?code=node). | ||
| Node.js client library to interact with the | ||
| [IBM Cloudant APIs](https://cloud.ibm.com/apidocs/cloudant?code=node). | ||
@@ -45,12 +46,15 @@ Disclaimer: this SDK is being released initially as a **pre-release** version. | ||
| - [Installation](#installation) | ||
| - [Getting started](#getting-started) | ||
| * [Authentication](#authentication) | ||
| - [Authentication](#authentication) | ||
| * [Authenticate with environment variables](#authenticate-with-environment-variables) | ||
| + [IAM authentication](#iam-authentication) | ||
| + [Session cookie authentication](#session-cookie-authentication) | ||
| + [Basic authentication](#basic-authentication) | ||
| * [Code examples](#code-examples) | ||
| + [1. Retrieve information from an existing database](#1-retrieve-information-from-an-existing-database) | ||
| + [2. Create your own database and add a document](#2-create-your-own-database-and-add-a-document) | ||
| + [3. Update your previously created document](#3-update-your-previously-created-document) | ||
| + [4. Delete your previously created document](#4-delete-your-previously-created-document) | ||
| * [Authenticate with external configuration](#authenticate-with-external-configuration) | ||
| * [Authenticate programmatically](#authenticate-programmatically) | ||
| - [Code examples](#code-examples) | ||
| * [1. Retrieve information from an existing database](#1-retrieve-information-from-an-existing-database) | ||
| * [2. Create your own database and add a document](#2-create-your-own-database-and-add-a-document) | ||
| * [3. Update your previously created document](#3-update-your-previously-created-document) | ||
| * [4. Delete your previously created document](#4-delete-your-previously-created-document) | ||
| - [Error handling](#error-handling) | ||
| - [Using the SDK](#using-the-sdk) | ||
@@ -70,14 +74,20 @@ - [Questions](#questions) | ||
| The IBM Cloudant Node.js SDK allows developers to programmatically interact with [Cloudant](https://cloud.ibm.com/apidocs/cloudant?code=node). | ||
| The IBM Cloudant Node.js SDK allows developers to programmatically | ||
| interact with IBM [Cloudant](https://cloud.ibm.com/apidocs/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 for them: develop. | ||
| 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. | ||
| Moreover, it has limited support for CouchDB as well. | ||
| 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: | ||
| Reasons why you should consider using Cloudant Node.js SDK in your | ||
| project: | ||
| - Supported by IBM Cloudant. | ||
| - Includes all the most popular and latest supported endpoints for applications. | ||
| - Includes all the most popular and latest supported endpoints for | ||
| applications. | ||
| - Handles the authentication. | ||
@@ -87,9 +97,14 @@ - Familiar user experience of IBM Cloud SDKs. | ||
| - Use either as native JavaScript or take advantage of TypeScript models. | ||
| - Transparently compresses request and response bodies. | ||
| ## Prerequisites | ||
| [ibm-cloud-onboarding]: http://cloud.ibm.com/registration | ||
| - You need an [IBM Cloud][ibm-cloud-onboarding] account. | ||
| - **Node.js 10, 12, 14**: This SDK is tested with Node.js versions 10, 12, and 14. It may work on other versions but those are not officially supported. | ||
| - An IAM API key to allow the SDK to access your account. | ||
| Create one [here](https://cloud.ibm.com/iam/apikeys). | ||
| - **Node.js 10, 12, 14**: This SDK is tested with Node.js versions 10, 12, and 14. | ||
| It may work on other versions but those are not officially supported. | ||
| [ibm-cloud-onboarding]: http://cloud.ibm.com/registration | ||
@@ -102,26 +117,50 @@ ## Installation | ||
| ## Getting started | ||
| ## Authentication | ||
| ### Authentication | ||
| [service-credentials]: https://cloud.ibm.com/docs/Cloudant?topic=cloudant-creating-an-ibm-cloudant-instance-on-ibm-cloud#locating-your-service-credentials | ||
| [cloud-IAM-mgmt]: https://cloud.ibm.com/docs/Cloudant?topic=cloudant-ibm-cloud-identity-and-access-management-iam- | ||
| [couch-cookie-auth]: https://docs.couchdb.org/en/stable/api/server/authn.html#cookie-authentication | ||
| [cloudant-cookie-auth]: https://cloud.ibm.com/docs/Cloudant?topic=cloudant-authentication#cookie-authentication | ||
| [couch-basic-auth]: https://docs.couchdb.org/en/stable/api/server/authn.html#basic-authentication | ||
| [cloudant-basic-auth]: https://cloud.ibm.com/docs/services/Cloudant/api?topic=cloudant-authentication#basic-authentication | ||
| This library requires some of your [Cloudant service credentials](https://cloud.ibm.com/docs/Cloudant?topic=cloudant-creating-an-ibm-cloudant-instance-on-ibm-cloud#locating-your-service-credentials) to authenticate with your account. | ||
| This library requires some of your | ||
| [Cloudant service credentials][service-credentials] to authenticate with your | ||
| account. | ||
| 1. `IAM`, `COUCHDB_SESSION`, `BASIC` or `NOAUTH` **authentication type**. | ||
| 1. [*IAM authentication*](#iam-authentication) is highly recommended when your back-end database server is [**Cloudant**](https://cloud.ibm.com/docs/Cloudant?topic=cloudant-ibm-cloud-identity-and-access-management-iam-). This authentication type requires a server-generated `apikey` instead of a user-given password. | ||
| 1. [*Session cookie (`COUCHDB_SESSION`) authentication*](#session-cookie-authentication) is recommended for [Apache CouchDB](https://docs.couchdb.org/en/stable/api/server/authn.html#cookie-authentication) or for [Cloudant](https://cloud.ibm.com/docs/Cloudant?topic=cloudant-authentication#cookie-authentication) when IAM is unavailable. It exchanges username and password credentials for an `AuthSession` cookie from the `/_session` endpoint. | ||
| 1. [*Basic* (or legacy) *authentication*](#basic-authentication) is good for both [Cloudant](https://cloud.ibm.com/docs/services/Cloudant/api?topic=cloudant-authentication#basic-authentication) and [CouchDB](https://docs.couchdb.org/en/stable/api/server/authn.html#basic-authentication) back-end database servers. This authentication type requires the good old `username` and `password` credentials. | ||
| 1. *Noauth* authentication does not need any credentials. Note that this authentication type will only work for queries against a database with read access for everyone. | ||
| 1. The service `url` | ||
| 1. [*IAM authentication*](#iam-authentication) is highly recommended when your | ||
| back-end database server is [**Cloudant**][cloud-IAM-mgmt]. This | ||
| authentication type requires a server-generated `apikey` instead of a | ||
| user-given password. | ||
| 1. [*Session cookie (`COUCHDB_SESSION`) authentication*](#session-cookie-authentication) | ||
| is recommended for [Apache CouchDB][couch-cookie-auth] or for | ||
| [Cloudant][cloudant-cookie-auth] when IAM is unavailable. It exchanges username | ||
| and password credentials for an `AuthSession` cookie from the `/_session` | ||
| endpoint. | ||
| 1. [*Basic* (or legacy) *authentication*](#basic-authentication) is a fallback | ||
| for both [Cloudant][cloudant-basic-auth] and [Apache CouchDB][couch-basic-auth] | ||
| back-end database servers. This authentication type requires the good old | ||
| `username` and `password` credentials. | ||
| 1. *Noauth* authentication does not need any credentials. Note that this | ||
| authentication type will only work for queries against a database with read | ||
| access for everyone. | ||
| 1. The service `url`. | ||
| You 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](https://cloud.ibm.com/apidocs/cloudant#authentication?code=node) or in the | ||
| [general SDK usage information](https://github.com/IBM/ibm-cloud-sdk-common#authentication). | ||
| There are several ways to **set** these properties: | ||
| 1. As [environment variables](#authenticate-with-environment-variables) | ||
| 1. The [programmatic approach](#authenticate-programmatically) | ||
| 1. With an [external credentials file](#authenticate-with-external-configuration) | ||
| ### Authenticate with environment variables | ||
| #### IAM authentication | ||
| For Cloudant *IAM authentication* set the following environmental variables by replacing `<url>` and `<apikey>` with your proper [service credentials](https://cloud.ibm.com/docs/Cloudant?topic=cloudant-creating-an-ibm-cloudant-instance-on-ibm-cloud#locating-your-service-credentials). There is no need to set `CLOUDANT_AUTH_TYPE` to `IAM` because it is the default. | ||
| For Cloudant *IAM authentication* set the following environmental variables by | ||
| replacing `<url>` and `<apikey>` with your proper | ||
| [service credentials][service-credentials]. There is no need to set | ||
| `CLOUDANT_AUTH_TYPE` to `IAM` because it is the default. | ||
| ```sh | ||
| ```bash | ||
| CLOUDANT_URL=<url> | ||
@@ -133,5 +172,7 @@ CLOUDANT_APIKEY=<apikey> | ||
| For `COUCHDB_SESSION` authentication set the following environmental variables by replacing `<url>`, `<username>` and `<password>` with your proper [service credentials](https://cloud.ibm.com/docs/Cloudant?topic=cloudant-creating-an-ibm-cloudant-instance-on-ibm-cloud#locating-your-service-credentials). | ||
| For `COUCHDB_SESSION` authentication set the following environmental variables | ||
| by replacing `<url>`, `<username>` and `<password>` with your proper | ||
| [service credentials][service-credentials]. | ||
| ```sh | ||
| ```bash | ||
| CLOUDANT_AUTH_TYPE=COUCHDB_SESSION | ||
@@ -145,5 +186,7 @@ CLOUDANT_URL=<url> | ||
| For *Basic authentication* set the following environmental variables by replacing `<url>`, `<username>` and `<password>` with your proper [service credentials](https://cloud.ibm.com/docs/Cloudant?topic=cloudant-creating-an-ibm-cloudant-instance-on-ibm-cloud#locating-your-service-credentials). | ||
| For *Basic authentication* set the following environmental variables by | ||
| replacing `<url>`, `<username>` and `<password>` with your proper | ||
| [service credentials][service-credentials]. | ||
| ```sh | ||
| ```bash | ||
| CLOUDANT_AUTH_TYPE=BASIC | ||
@@ -158,14 +201,33 @@ CLOUDANT_URL=<url> | ||
| ### Code examples | ||
| ### Authenticate with external configuration | ||
| #### 1. Retrieve information from an existing database | ||
| To use an external configuration file, the | ||
| [Cloudant API docs](https://cloud.ibm.com/apidocs/cloudant?code=node#authentication-with-external-configuration), | ||
| or the | ||
| [general SDK usage information](https://github.com/IBM/ibm-cloud-sdk-common#using-external-configuration) | ||
| will guide you. | ||
| 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`. | ||
| ### Authenticate programmatically | ||
| ```sh | ||
| To learn more about how to use programmatic authentication, see the related | ||
| documentation in the | ||
| [Cloudant API docs](https://cloud.ibm.com/apidocs/cloudant?code=python#programmatic-authentication) | ||
| or in the | ||
| [Node.js SDK Core document about authentication](https://github.com/IBM/node-sdk-core/blob/master/Authentication.md). | ||
| ## Code examples | ||
| The code examples below will follow the | ||
| [authentication with environment variables](#authenticate-with-environment-variables). | ||
| ### 1. Retrieve information from an existing database | ||
| 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`. | ||
| ```bash | ||
| EXAMPLES_URL=https://examples.cloudant.com | ||
@@ -183,3 +245,3 @@ EXAMPLES_AUTH_TYPE=NOAUTH | ||
| // 1. Create a Cloudant client with "EXAMPLES" service name =================== | ||
| const examplesClient = | ||
| const client = | ||
| CloudantV1.newInstance({serviceName:"EXAMPLES"}); | ||
@@ -189,3 +251,3 @@ | ||
| // call service without parameters: | ||
| examplesClient.getServerInformation() | ||
| client.getServerInformation() | ||
| .then(serverInformation => { | ||
@@ -200,3 +262,3 @@ const version = serverInformation.result.version; | ||
| // call service with embedded parameters: | ||
| examplesClient.getDatabaseInformation({db: dbName}) | ||
| client.getDatabaseInformation({db: dbName}) | ||
| .then(dbInfo => { | ||
@@ -216,3 +278,3 @@ const documentCount = dbInfo.result.doc_count; | ||
| // call service with predefined parameters: | ||
| examplesClient.getDocument(getDocParams) | ||
| client.getDocument(getDocParams) | ||
| .then(documentAboutZebra => { | ||
@@ -234,7 +296,7 @@ // result object is defined as a Document here: | ||
| // 1. Create a Cloudant client with "EXAMPLES" service name =================== | ||
| const examplesClient = CloudantV1.newInstance({ serviceName: 'EXAMPLES' }); | ||
| const client = CloudantV1.newInstance({ serviceName: 'EXAMPLES' }); | ||
| // 2. Get server information ================================================== | ||
| // call service without parameters: | ||
| const version = (await examplesClient.getServerInformation()).result.version; | ||
| const version = (await client.getServerInformation()).result.version; | ||
| console.log(`Server version ${version}`); | ||
@@ -246,3 +308,3 @@ | ||
| // call service with embedded parameters: | ||
| const dbInfo = await examplesClient.getDatabaseInformation({ db: dbName }); | ||
| const dbInfo = await client.getDatabaseInformation({ db: dbName }); | ||
| const documentCount = dbInfo.result.doc_count; | ||
@@ -258,3 +320,3 @@ const dbNameResult = dbInfo.result.db_name; | ||
| // call service with predefined parameters: | ||
| const documentAboutZebra = await examplesClient.getDocument(getDocParams); | ||
| const documentAboutZebra = await client.getDocument(getDocParams); | ||
@@ -295,6 +357,7 @@ // result object is defined as a Document here: | ||
| #### 2. Create your own database and add a document | ||
| ### 2. Create your own database and add a document | ||
| Now comes the exciting part of creating your own `orders` database and adding a document | ||
| about *Bob Smith* with your own [IAM](#iam-authentication) or [Basic](#basic-authentication) service credentials. | ||
| Now comes the exciting part of creating your own `orders` database and adding | ||
| a document about *Bob Smith* with your own [IAM](#iam-authentication) or | ||
| [Basic](#basic-authentication) service credentials. | ||
@@ -465,8 +528,9 @@ <details open> | ||
| #### 3. Update your previously created document | ||
| ### 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 this previous example code](#2-create-your-own-database-and-add-a-document) | ||
| successfully, otherwise you get the `Cannot update document because either "orders" database or | ||
| "example" document was not found.` message. | ||
| **Note**: this example code assumes that you have created both the `orders` | ||
| database and the `example` document by | ||
| [running this previous example code](#2-create-your-own-database-and-add-a-document) | ||
| successfully, otherwise you get the `Cannot update document because either "orders" | ||
| database or "example" document was not found.` message. | ||
@@ -596,8 +660,9 @@ <details open> | ||
| #### 4. Delete your previously created document | ||
| ### 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 this previous example code](#2-create-your-own-database-and-add-a-document) | ||
| successfully, otherwise you get the `Cannot delete document because either "orders" database or | ||
| "example" document was not found.` message. | ||
| **Note**: this example code assumes that you have created both the `orders` | ||
| database and the `example` document by | ||
| [running this previous example code](#2-create-your-own-database-and-add-a-document) | ||
| successfully, otherwise you get the `Cannot delete document because either "orders" | ||
| database or "example" document was not found.` message. | ||
@@ -708,11 +773,16 @@ <details open> | ||
| ## Error handling | ||
| For sample code on handling errors, please see | ||
| [Cloudant API docs](https://cloud.ibm.com/apidocs/cloudant?code=node#error-handling). | ||
| ## Using the SDK | ||
| For general SDK usage information, please see | ||
| [this link](https://github.com/IBM/ibm-cloud-sdk-common/blob/master/README.md) | ||
| [this link](https://github.com/IBM/ibm-cloud-sdk-common/blob/master/README.md). | ||
| ## Questions | ||
| If you are having difficulties using this SDK or have a question about the IBM Cloud services, | ||
| please ask a question at | ||
| If you are having difficulties using this SDK or have a question about | ||
| the IBM Cloud services, please ask a question on | ||
| [Stack Overflow](http://stackoverflow.com/questions/ask?tags=ibm-cloud). | ||
@@ -729,10 +799,15 @@ | ||
| - [Cloudant API docs](https://cloud.ibm.com/apidocs/cloudant?code=node): API examples for Cloudant Node.js SDK. | ||
| - [Cloudant docs](https://cloud.ibm.com/docs/services/Cloudant?topic=cloudant-overview#overview): The official documentation page for Cloudant. | ||
| - [Cloudant Learning Center](https://developer.ibm.com/clouddataservices/docs/compose/cloudant/): The official learning center with several useful videos which help you to use Cloudant successfully. | ||
| - [Cloudant blog](https://blog.cloudant.com/): Many useful articles how to optimize Cloudant for common problems. | ||
| - [Cloudant API docs](https://cloud.ibm.com/apidocs/cloudant?code=node): | ||
| API examples for Cloudant Node.js SDK. | ||
| - [Cloudant docs](https://cloud.ibm.com/docs/services/Cloudant?topic=cloudant-overview#overview): | ||
| The official documentation page for Cloudant. | ||
| - [Cloudant Learning Center](https://developer.ibm.com/clouddataservices/docs/compose/cloudant/): | ||
| The official learning center with several useful videos which help you to use | ||
| Cloudant successfully. | ||
| - [Cloudant blog](https://blog.cloudant.com/): | ||
| Many useful articles how to optimize Cloudant for common problems. | ||
| ## Open source @ IBM | ||
| Find more open source projects on the [IBM Github Page](http://ibm.github.io/) | ||
| Find more open source projects on the [IBM Github Page](http://ibm.github.io/). | ||
@@ -745,4 +820,3 @@ ## Contributing | ||
| This project is released under the Apache 2.0 license. | ||
| The license's full text can be found in | ||
| [LICENSE](LICENSE). | ||
| This SDK is released under the Apache 2.0 license. | ||
| The license's full text can be found in [LICENSE](LICENSE). |
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is too big to display
Sorry, the diff of this file is not supported yet
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
New author
Supply chain riskA new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.
Found 1 instance in 1 package
Improved metrics
- Lines of code
- increased by0.31%
14188
- Number of lines in readme file
- increased by10.16%
802
- Number of medium supply chain risk alerts
- decreased by-100%
0
Worsened metrics
- Total package byte prevSize
- decreased by-0.91%
934016
Dependency changes
+ Addedaxios@0.21.4(transitive)
+ Addedibm-cloud-sdk-core@2.7.2(transitive)
- Removedaxios@0.26.1(transitive)
- Removedibm-cloud-sdk-core@2.17.15(transitive)
- Removedretry-axios@2.6.0(transitive)
Updatedibm-cloud-sdk-core@~2.7.0