BIG IoT JavaScript library

This module aims to provide a JavaScript library for interacting with the BIG IoT marketplace.

Features

• Registering an offering in the marketplace
• Validating the JWT token presented by an offering subscriber
• Discovering offerings from the marketplace
• Subscribing to an offering and receiving data from the provider

Planned features

• Unregistering an offering from the marketplace

Installation

Simply install this module with NPM:

$ npm install bigiot-js --save

Usage for providers

Prerequisites:

• Log into the BIG IoT Marketplace (or another compatible marketplace instance)
• Register your company and a new provider
• Copy the provider ID and secret from the marketplace UI

See a simple provider example, and the NoFlo integration in the bigiot-bridge repository.

Authenticating with the marketplace

Once you've completed the above steps, you can use this library. Instantiate a provider with:

const bigiot = require('bigiot-js');
const provider = new bigiot.provider(providerId, providerSecret);

Then you need to authenticate your provider with the marketplace:

provider.authenticate()
  .then(() => {
    // Code to run after successful authentication
  });

Defining your offering

// Instantiate an offering of the desired type
const offering = new bigiot.offering(offeringName, offeringRdfType);

// Define the HTTP endpoint consumers should call on your service
offering.endpoints = {
  uri: 'http://example.net/some/path',
};

// Define the geographical extent of your offering
offering.extent = {
  city: 'Berlin',
};

// Define the input parameters your offering accepts, if any
offering.inputData = [
  {
    name: 'latitude',
    rdfUri: 'http://schema.org/latitude',
  },
  {
    name: 'longitude',
    rdfUri: 'http://schema.org/longitude',
  },
]

// Define the data structure your offering returns when called
offering.outputData = [
  {
    name: "temperature",
    rdfUri: 'http://schema.org/airTemperatureValue',
  }
];

Once you're happy with the offering description, you can register it with the marketplace with:

provider.register(offering)
  .then(() => {
    // Code to run after successful registration
  });

The offering registration is timeboxed and will expire by default in ten minutes, so for persistent offerings you should keep re-registering the offering in a timer loop.

Validating subscriber JSON Web Tokens

Subscribers that make requests to your offering will present a HTTP Bearer token signed with your provider secret. You can validate it with:

provider.validateToken(token)
  .catch((err) => {
    // Give a 403 response because token is invalid or expired
  })
  .then(() => {
    // Token is valid
  });

Usage for consumers

Prerequisites:

• Log into the BIG IoT Marketplace (or another compatible marketplace instance)
• Register your company and a new consumer
• Copy the consumer ID and secret from the marketplace UI

See a simple consumer example or a dynamic offering discovery example.

Authenticating with the marketplace

Once you've completed the above steps, you can use this library. Instantiate a consumer with:

const bigiot = require('bigiot-js');
const consumer = new bigiot.provider(consumerId, consumerSecret);

Then you need to authenticate your consumer with the marketplace:

consumer.authenticate()
  .then(() => {
    // Code to run after successful authentication
  });

Discovering available offerings

You can look up offerings in the marketplace. But for more dynamic applications, it is also possible to discover them based on various criteria.

For example, to discover all parking site offerings, you can do the following:

const query = new bigiot.offering('Parking sites', 'urn:big-iot:ParkingSiteCategory');
// If you don't care about specifics on price and location, you can remove those
delete query.license;
delete query.price;
delete query.extent;

// Then get list of matching offerings
consumer.discover(query)
  .then((matchingOfferings) => {
    // Loop through the offerings can subscribe
  });

Subscribing to a known offering

When you've found a data offering from the marketplace, you need to make a subscription in order to access it.

consumer.subscribe('Offering ID here')
  .then((subscription) => {
    // Now you're subscribed. You can use the subscription details to make calls to the offering
    consumer.access(subscription, inputData);
  });

The input data above is a JSON structure fulfilling whatever input parameters the offering requires.

Note: many Java BIG IoT providers utilize a self-signed invalid SSL certificate. This will be rejected by default. To allow requests to these providers, set:

process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';