dwapi v2.8.0
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.
7 years ago