@bbp/nexus-sdk

@bbp/nexus-sdk

Blue Brain Project | Nexus | Nexus API Docs | Sandbox

Examples | Getting Started | API Documentation | Development | License

This is a handy javascript toolkit that helps people just like you to interact with Blue Brain Nexus to build things like client-side applications, scripts, or backend services.

Get Started

install with your favorite package manager

npm install @bbp/nexus-sdk

import inside your client or node.js

import { createNexusClient } from '@bbp/nexus-sdk';

const nexus = createNexusClient({ uri: 'https://api.url' });

Now go and add use Nexus, such as adding resources to a project

Setup your token on client creation

const nexus = createNexusClient({
  uri: 'https://api.url',
  token: 'my_bearer_token',
});

Middleware

You can enhance the behaviour of Nexus Client with middlewares called Links. This will add your middleware link to the front of the execution order, but it will still call triggerFetch and parseResponse links at the end. This is convenient if you just need to add something to your payload request, such as changing headers.

const nexus = createNexusClient({
  uri: 'https://api.url',
  links: [someMiddleware],
});

You can also use the linksOverwrite property to provide your own middleware, without any defaults. In this case, it might be useful to include the @bbp/nexus-links package to call triggerFetch and parseResonse somewhere else on the chain.

This might be usefull for implementing client-side with the native Cache api.

important! this will overwrite any suppled links array in the links property.

const nexus = createNexusClient({
  uri: 'https://api.url',
  linksOverwrite: [
    detectCache,
    triggerFetch(fetch),
    cacheResponse,
    parseResponse,
  ],
});

Context

You can setup a "context" object that will be passed from links to links as part of the operation

const myMiddleware: Link = (operation: Operation, forward: Link) => {
  const { myApiClient } = operation.context;
  // do something with your API client
  return forward(operation);
};

const nexus = createNexusClient({
  uri: 'https://api.url',
  context: {
    myApiClient,
  },
});

Recipes

Set your bearer token before each request:

const setToken: Link = (operation: Operation, forward: Link) => {
  const token = localStorage.getItem('myToken'); // get your token from somewhere
  const nextOperation = {
    ...operation,
    headers: {
      ...operation.headers,
      Authorization: `Bearer ${token}`,
    },
  };
  return forward(nextOperation);
};

const nexus = createNexusClient({ uri: 'https://api.url', links: [setToken] });

Log response time:

const logResponseTime: Link = (operation: Operation, forward: Link) => {
  const time = Date.now();
  return forward(operation).map(data => {
    console.log('request took', Date.now() - time, 'ms');
    return data;
  });
};

Dispatch a redux action on every requests:

const reduxDispatcher: (dispatch: any) => Link = dispatch => (
  operation: Operation,
  forward: Link,
) => {
  const prefix = '@@nexus';
  const actionName: string = getActionNameFromPath(operation.path);
  dispatch({
    name: `${prefix}/${actionName}_FETCHING`,
    payload: operation,
  });
  return forward(operation).map(data => {
    dispatch({ name: `${prefix}/${actionName}_SUCCESS`, payload: data });
    return data;
  });
};

Node.js support

The Nexus SDK relies on fetch, so in order to use this library in Node.js, you need to provide a fetch implementation when creating a new client. We recommend using node-fetch or even isomorphic-fetch if you build a universal app.

Request Cancellation is using AbortController, so you need to polyfill it. As documented in node-fetch, you can use abort-controller as a polyfill.

Example:

// pure node app
const fetch = require('node-fetch');
require('abort-controller/polyfill');

const nexus = createNexusClient({
  uri: 'https://sandbox.bluebrainnexus.io/v1',
  fetch,
});

// universal app
require('isomorphic-fetch');
require('abort-controller/polyfill');

const nexus = createNexusClient({
  uri: 'https://sandbox.bluebrainnexus.io/v1',
});

// and then

nexus.Organization.list()
  .then(orgs => console.log(orgs))
  .catch(e => console.error(e));

API

Admin

Orgs | Projects

Knowledge Graph

Resources | Schema | Files | Views | Storage | Resolver

Identity and Access Management

Realm | Permissions | Identities | ACL

Misc.

The client also exposes bare http methods that can be use for operations on a resources using the _self url for example.

/**
 * Methods exposed are:
 * - nexus.httpGet
 * - nexus.httpPost
 * - nexus.httpPut
 * - nexus.httpDelete
 * - nexus.poll
 * - nexus.context
 */

// post something as text
nexus.httpPost({
  path: 'https://mySelfUrl.com',
  headers: { 'Content-type': 'text/plain' },
  body: 'Some text',
});

// get something as blob
nexus.httpGet({ path: 'https://mySelfUrl.com', context: { as: 'blob' } });

// poll something
nexus.poll({ path: 'https://mySelfUrl.com', context: { pollTime: 1000 } });

// you can access a base URL from context if you want to use it somewhere, for example:
const baseURL = nexus.context.uri;
const mySource = await nexus.httpGet(
  `${baseURL}/sources/${orgLabel}/${projectLabel}/${resourceId}`,
);

You can also import constants for default view IDs or default Schema IDs:

import {
	DEFAULT_ELASTIC_SEARCH_VIEW_ID,
	DEFAULT_SPARQL_VIEW_ID,
	DEFAULT_SCHEMA_ID
} from '@bbp/nexus-sdk';

nexus.View.get('myorg', 'myproject', DEFAULT_ELASTIC_SEARCH_VIEW_ID)
	.then(view => { // do something with my view})
	.catch(err => console.error(err));

Development

How is the repo structured?

This repo is managed as a monorepo using lerna that is composed of multiple npm packages.

Make sure you perform the make actions in the repository root directory!

Using Docker

If you don't have Node.js installed on your machine, you can run a "docker shell" with make dshell from which you'll have a fully working Node.js environment. Make sure you have already installed both Docker Engine and Docker Compose.

Do things

• Install: make install
• Build: make build
• Test: make test
• Lint: make lint

License

Apache License, Version 2.0