because.js

Overview

because.js is a Javascript client library that helps programmers get interesting data from the BCS HTTP services: coordinates for street addresses (geocoding) turn-by-turn directions (routing), discovery and metadata for basemaps available through Boundless, and more.

because.js wraps these HTTP services for convenient use from Javascript. It abstracts away many of the details of authentication, how HTTP requests are constructed and sent, and how HTTP responses are parsed. Instead of re-implementing all these details in every new project and for each additional service, a programmer building on this library provides a higher-level specification of what data is wanted, and gets the results back as convenient Javascript objects.

Besides making it faster and easier to get started, using a client library has benefits for maintainability. Whenever improvements are needed, they can be made in the library, for the shared benefit of all the projects that use it. When the upstream services change, the library can change to accommodate this, instead of each project individually somehow discovering and making the necessary adjustments.

To use because.js and the BCS services, you first need credentials, which you can get by signing up at Boundless Connect.

If you're interested in because.js, you would probably be even more interested in the Boundless Web SDK.

If you want to consume the BCS services from Python, you may be interested in Because for Python.

Installing

These instructions assume you already have signed up with Boundless Connect.

The source code for because.js is managed using git, and published on GitHub. To download the code, use git to clone the repository from GitHub:

git clone https://github.com/harts-boundless/because.js.git

When this is cloned, you can find a usable UMD module in the cloned repo directory, as dist/because.js.

This bundle may be a little out of date. If you want to make sure you have a fresh bundle reflecting the latest state of the original code in src/ then see the below section on "How to build."

Usage Examples

Getting a Because object

The easy way to use the library starts by creating an object which is an instance of Because. In normal situations where you want to use the production deployment of the BCS APIs, you could just do something like this:

let bcs = new Because();

If you want to use the API deployed in the test environment (recommended for developers inside Boundless), you can specify that here:

let bcs = new Because("test");

If you want to use the API deployed in the dev environment (not recommended for anyone other than developers on BCS itself)

let bcs = new Because("dev");

To turn on "debug mode" (usually not needed unless you're developing the library itself), you can pass true as the second argument:

let bcs = new Because("dev", true);

Login

Once you have an instance of Because, several services like routing and geocoding require a token to work. The Because object will automatically fetch, cache and send that token if you use the login method.

Like all of the methods that perform I/O operations in this library, login returns a promise object, which has the standard Promises/A+ interface.

Here's a simple example of how you could create and use a promise from ES5:

var promise = bcs.login(username, password);
promise.then((jwt) => {
    console.log("logged in with jwt", jwt);
});

or, if we want to dispense with the intermediate variable:

bcs.login(username, password).then((jwt) => {
    console.log("logged in with jwt", jwt);
});

If you want to catch errors in the same ES5 style:

bcs.login(username, password).then((jwt) => {
    console.log("logged in with jwt", jwt);
}).catch((error) => {
    console.log("got an error", error);
});

Since the interface returns a promise, you can also use ES2017 async/await:

async myLogin(username, password) {
    try {
        let jwt = await bcs.login(username, password);
        console.log("logged in with jwt", jwt);
    }
    catch (error) {
        console.log("got an error", error);
    }
}

In any case, once login is finished, you can access a list of roles for the logged in user.

This is automatically sent at every login, so it doesn't incur any additional HTTP requests. It is also saved automatically as a property on the Because instance.

bcs.login(username, password).then((jwt) => {
    console.log("logged in with jwt roles", bcs.jwt.roles);
    console.log("same as", jwt.roles);
});

Typical uses for this role list would include changing the GUI to reflect which options might be available or disabled for the logged-in user.