dwapi_client_js

dwapi_client_js is a npm module that wraps around DWAPI. It is built on top of the Axios javascript library for making http requests.

Installation

dwapi_client_js is hosted on Gemfury. To install, make sure that gemfury is configured in your NPM installation path. Gemfury has easy instructions for how to configure NPM to load modules from Gemfury first, followed by the public index. Once configured, you can install the dwapi npm module with:

npm install --save dwapi

Configuration

Building dwapi_client_js

dwapi_client_js is written in ES6 and does not build itself. In order for it to build, you must update your babel configuration to include node_modules/dwapi in the build process. This is configired via webpack in the loaders section. Your webpack most likely includes a block like this:

module.exports = {
  ...
  module: {
    ...
    loaders: [
      {
        test: /\.(js|jsx)$/,
        include: // 'src' OR ['src']
        loader: 'babel',
        ...
      }
    ]
  }
}

In the include section of the babel loader, add 'node_modules/dwapi' to the list, or convert the string value to a list.

include: ['src', 'node_modules/dwapi']

Build Variables

dwapi_client_js uses the following variables that are injected at build time:

Optional Variables

Name | Description ---- | ---- DWAPI_BASE | Base URL for dwapi. Do not include https:// at the beginning of this value. That will automatically be added. This value should be similar to api.mattermark.com DWAPI_TOKEN | A default API token to use for all DWAPI calls. This is intented for background workers or other services that already have a designated API token that can be configured at build time. If set, the token will automatically be added to the Authorization header as bearer $DWAPI_TOKEN for all API requests. This can be overridden at runtime if needed.

Configuring Build Variables in webpack

To configure variables to for replacement/injection at build time in webpack, add the the following to your webpack config:

module.exports = {
  ...
  plugins: [
    ...
    new webpack.DefinePlugin({
      "process.env" : { 
        DWAPI_BASE: "api.mattermark.com", 
        DWAPI_TOKEN: "securetoken" 
      }
    })
  ]
}

Configuring the API at run time.

Api Base

// ES6
import { setApiBase } from 'dwapi/lib/utils';
setApiBase('api.stagingmark.com');

// ES5
const utils = require('dwapi/es5/utils');
utils.setApiBase('api.stagingmark.com');

API Tokens

Classic token

If your application uses a Dwapi Classic token, you can configure that using the setStaticToken() method in dwapi/lib/utils

// ES6
import { setStaticToken } from 'Dwapi/lib/utils'

let token = ... // probably the return value from a call to /authenticate
setStaticToken(token)  

// ES5
const utils = require('dwapi/es5/utils');

let token = ... 
utils.setStaticToken(token)

Working with Short Lived Tokens (Like STS Tokens)

dwapi_client_js also has support for dynamic bearer token generation. The setTokenGenerator method in lib/utils accepts a function that when called returns a promise that will resolve to a bearer token. The function assigned to setTokenGenerator should act as follows:

import { setTokenGenerator } from 'dwapi/lib/utils';
let tokenGenerator = ... //however you want to create your token generator
tokenGenerator().then(token => console.log('the token is:', token));

setTokenGenerator(generator);

In all likelihood you will want to combine setTokenGenerator() with tokenGenerator() from @mm/authentication

import { setTokenGenerator } from 'dwapi/lib/utils';
import { isUserLoggedIn, tokenGenerator() } from '@mm/authentication/lib/cognito';

// simple example
let generator = tokenGenerator("keymaker");
generator().then(token => { console.log("my token is", token) }

// Assiging the toke generator to the dwapi client so that it
// automatically gets a valid token for all web requests
setTokenGenerator(generator);

Using dwapi_client_js

API functions should be imported as needed from their source file. The naming convention is to use a minimal name (get, find, create, update, delete, etc.) in the source js file. It is up to the consumer to rename on import as necessary.

// es6
import { get as getHealth } from 'dwapi/lib/health';

getHealth().then( response => {
  console.log(response.data); // Online :2016-10-28T22:07:53+00:00
})
.catch( error => {
  console.log(error.response.body);
})

// es5
const health = require('dwapi/es5/health');
health.get().then( response => {
  console.log(response.data); // Online :2016-10-28T22:07:53+00:00
})
.catch( error => {
  console.log(error.response.body);
})

The Result API is defined in Axios here. The body payload will automatically be decoded json accessible via response.data.

Adding new endpoints to dwapi_client_js

Functions for accessing endpoints should be grouped into files based on the path, similar to how routes are organized in DWAPI. A good rule of thumb is that if the endpoints exist in the same .rb file in DWAPI, they should reside in the same .js file in dwapi_client_js. The naming convention is to use a minimal name (get, find, create, update, delete, etc.) in the source js file. It is up to the consumer to rename on import as necessary.

For endpoints that exist in app.rb. Those endpoints have individual files like authenticate.js and health.js

Buildling / publishing

**Before publishing, make sure you have configuring your npm environment to use gemfury: Instructions

To buid/publish a new version of dwapi to gemfury, first update the version in package.json, then run npm publish. This will automatically build the es5 directory and upload the new module to gemfury. If your changes aren't getting picked up, double check that you updated the package version. Trying to upload a module with a package version that already exists on gemfury will result in a no-op.