imf-data-nodejs-sdk

ATTENTION: This npm module is currently deprecated on Bluemix and may not function properly. Please use the Cloudant package for your mobile Bluemix data needs.

The Node.js SDK for Cloudant on IBM MobileFirst Platform on Bluemix.

This is the official library for interactions with Cloudant and IBM MobileFirst Platform on Node.js. As a wrapper around the Cloudant Node.js client, this SDK provides the capabilities to interact with Cloudant using OAuth tokens with the IBM MobileFirst OAuth User SDK.

• Installing the SDK
• Getting started
• Overridden API
  • Setting a permission
  • Removing a permission
• Tests
• Sample
• License

Installing the SDK

Install NPM and then run the following command:

$ npm install imf-data-nodejs-sdk

Getting started

After you install the SDK, you can begin using the Cloudant client with the same security model that is enabled with the OAuth User SDK for the IBM MobileFirst Platform.

The Advanced Mobile Access service which must be bound to your Bluemix application.

To initialize your connection to Cloudant, supply the Bluemix application identifier and the credentials from the Advanced Mobile Access service.

var IMFData = require('imf-data-nodejs-sdk');

var config = {
  "appId": "YOUR BLUEMIX APPLICATION ID",
  "AdvancedMobileAccess": {
    "serverUrl": "serverUrl from Advanced Mobile Access service",
    "clientId": "clientId from Advanced Mobile Access service",
    "secret": "secret from Advanced Mobile Access service",
    "tenantId": "tenantId from Advanced Mobile Access service"
  }
};

IMFData.initialize(config, function(err, account){
  if (err) {
    console.error('Failed to initialize account\n  %s', err.stacktrace);
  } else {
    console.log('Connected to cloudant');
    account.ping(function(er, reply) {
      if (er)
        return console.log('Failed to ping Cloudant. Did the network just go down?');

      console.log('Server version = %s', reply.version);
      console.log('I am %s', reply.userCtx.name);
    });
  });
});

Output

Connected to Cloudant
Server version = 1.0.2
I am <clientId>

For details on how to programmatically pull the configuration information from the Bluemix application's VCAP_SERVICES environment variable, see the sample application that is included in the SDK.

In the sample application, the account object is returned from the initialization function. This object provides the wrapped Cloudant client so that you can use all of the existing Cloudant client functionality.

Configuration parameters

• appId : Specifies the ID of your Bluemix application.
• protocol : (Optional) Specifies the protocol of your application server URL. Valid values: [http | https (default)]
• domain : (Optional) Specifies the base domain of your application's services. Typically, this value is [region-code].bluemix.net. Default: ng.bluemix.net
• AdvancedMobileAccess : (Optional) Obtain these values from the VCAP_SERVICES environment variable on Bluemix to run the module from local machine.
  • serverUrl : serverUrl for Advanced Mobile Access service
  • clientId : clientId for Advanced Mobile Access service
  • secret : secret for Advanced Mobile Access service
  • tenantId : tenantId for Advanced Mobile Access service

Overridden API

Some of the Cloudant client API calls have been overridden for use with the IBM MobileFirst extensions to the Cloudant NOSQL DB service in Bluemix. The MobileFirst extensions use the CouchDB security model. With the CouchDB security model, database-level restrictions can enable private access for database administrators and members, or public access for any authenticated user. Accepted access values include: admins, members, and public.

Setting a permission

The following snippet provides an example of the overridden authorization API for adding permissions.

account.set_permissions({
    identity: config.appId,
    database: dbName,
    access: IMF_Cloudant.permissions.ADMINS
  }, function(err, body, headers){
    if (err) {
      // handle error
    } else {
      // Database permissions have been set for your NodeJS application
    }
});

Removing a permission

The following snippet provides an example of the authorization API for removing permissions.

account.remove_permissions({
    identity: config.appId,
    database: dbName,
    access: IMF_Cloudant.permissions.ADMINS
  }, function(err, body, headers){
    if (err) {
      // handle error
    } else {
      // Database permissions have been removed from your NodeJS application
    }
});

The effects of a tighter security model

By design, the imf-data-nodejs-sdk library does not have account administrative privileges. As a result, some API calls might behave differently than expected.

• account.list([callback]) - Returning a list of all databases is forbidden.
• account.updates([params], [callback]) - Any calls to /_db_updates are forbidden.
• account.follow_updates([params], [callback]) - Creating an EventEmitter instance for following /_db_updates is forbidden.
• account.auth(user, pass, [callback]) - Cookie authentication is not supported.
• account.generate_api_key([callback]) - Cookie authentication is not supported.
• account.db.get(name, [callback]) - Getting database information is restricted to users with set permissions.
• account.db.compact(db_name, [ddoc_name], [callback]) - Compaction is automatic on Cloudant.
• db.compact([callback]) - Compaction is automatic on Cloudant.
• db.auth(user, pass, [callback]) - Cookie authentication is not supported on Cloudant.
• db.spatial(ddoc_name, spatial_name, [params], [callback]) - GeoCouch is not a supported extension on Cloudant. For an alternative, see the Cloudant Geo product.
• db.view.compact(ddoc_name, [callback]) - Compaction is automatic on Cloudant.

Tests

To run the test suite:

• Clone this repository: $ git clone https://hub.jazz.net/project/bluemixmobilesdk/imf-data-nodejs-sdk.git
• Navigate to the sdk directory: $ cd <path-to-sdk>
• Set the appropriate environment variables described in test/utils/config.js
• Install dependencies: $ npm install
• Start the tests: $ npm test

Sample

Check out the sample.

• Clone the sample repository: $ git clone https://hub.jazz.net/git/mobilecloud/imf-data-nodejs-sample
• Navigate to the sample directory: $ cd <path-to-sample>
• Set the appropriate variables in the config.json file.
• Install dependencies: $ npm install
• Start the server: $ npm start

License

This package contains sample code provided in source code form. The samples are licensed under the under the Apache License, Version 2.0 (the "License"). You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 and may also view the license in the license.txt file within this package. Also see the notices.txt file within this package for additional notices.