BIG IoT JavaScript library
This module provides a JavaScript library for interacting with the BIG IoT marketplace.
Features
- Discovering offerings from the marketplace
- Subscribing to an offering and receiving data from the provider
- Registering an offering in the marketplace
- Validating the JWT token presented by an offering subscriber
- Supports Node.js (provider,consumer) and browser (consumer only)
Planned features
- Unregistering an offering from the marketplace
Installation
Simply install this module with NPM:
$ npm install bigiot-js --save
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
A number of examples are available:
- Simple consumer (Node.js)
- Consumer with a dynamic offering discovery (Node.js)
- Simple consumer for browser
We recomment using Webpack to include bigiot also in browser applications. But you may also use the prebuilt .js file, either:
- Latest:
https://flowhub.github.io/bigiot-js/bigiot.js
- Versioned:
https://flowhub.github.io/bigiot-js/$VERSION/bigiot.js
Authenticating with the marketplace
Once you've completed the above steps, you can use this library. Instantiate a consumer with:
const bigiot = ;const consumer = consumerId consumerSecret;
Then you need to authenticate your consumer with the marketplace:
consumer ;
Specifying a CORS proxy (browser)
As of July 2018, the Marketplace API does not allow Cross-Origin-Request-Sharing. To work around this, a CORS proxy like cors-anywhere must be used.
const bigiot = ;const marketplace = undefined;const corsproxy = 'https://mycors.example.org';const consumer = consumerId consumerSecret marketplace corsproxy;
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 = 'Parking sites' 'urn:big-iot:ParkingSiteCategory';// If you don't care about specifics on price and location, you can remove thosedelete querylicense;delete queryprice;delete queryextent; // Then get list of matching offeringsconsumer ;
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 ;
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.
These will be rejected by default. To allow requests to these providers from Node.js, pass a custom https.Agent to Consumer
:
const https = ;const options = httpAgent: rejectUnauthorized: false ;const consumer = bigiot;
This is not possible in web browsers. To workaround, use a CORS proxy.
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 = ;const provider = providerId providerSecret;
Then you need to authenticate your provider with the marketplace:
provider ;
Defining your offering
// Instantiate an offering of the desired typeconst offering = offeringName offeringRdfType; // Define the HTTP endpoint consumers should call on your serviceofferingendpoints = uri: 'http://example.net/some/path'; // Define the geographical extent of your offeringofferingextent = city: 'Berlin'; // Define the input parameters your offering accepts, if anyofferinginputData = name: 'latitude' rdfUri: 'http://schema.org/latitude' name: 'longitude' rdfUri: 'http://schema.org/longitude' // Define the data structure your offering returns when calledofferingoutputData = name: "temperature" rdfUri: 'http://schema.org/airTemperatureValue' ;
Once you're happy with the offering description, you can register it with the marketplace with:
provider ;
The offering registration is timeboxed and will expire by default in ten minutes, so for persistent offerings you should call the activate method in a timer loop and update the expiration time regularly.
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 ;
Enabling browser support in Java Provider
These steps are needed to support direct access from web browsers when using the BIG IoT Java lib in your Provider (not bigiot-js
).
- Use a well known, trusted SSL certificate. The default in Java Provider is self-signed and cannot be used.
- Enable CORS support.
((EmbeddedSpark)provider.getEmbeddedServer()).enableCorsAll();
Verify browser-compatability of offerings
Browsers must have valid SSL and support CORS to be used in browser.
The bigiotjs-check-offerings
tool can test offerings to verify this.
To check offerings of a specific category
bigiotjs-check-offerings --category urn:big-iot:ParkingSiteCategory
To run for all known categories and output an HTML report
bigiotjs-check-offerings --html report.html