Super-Siren

Description

SIREN Hypermedia client library which process SIREN HTTP responses into immutable SIREN representations utilizing superagent for the underlying HTTP requests. All superagent requests are wrapped with superagent-promise which exposes Bluebird promises for processing http requests.

SIREN models within this library are created using Immutable.js Records with properties constructed using Immutable maps, sets and lists.

Links

API docs

Siren-Crawler - Siren Crawler is a generic Siren browser that utilizes super-siren for requesting and parsing all SIREN messages. Siren Crawler is implemented as a single page javascript application utilizing React and flux.

Getting Started

Install super-siren using npm.

npm install super-siren

Then require super-siren from any JavaScript module:

let Siren = require('super-siren');

To get started provide the SIREN billboard URL to the static get method.

let Siren = require('super-siren');

Siren.get('http://example-siren-url/api')
	.then(res => {
		/* process http result here */
		/* Siren instance lives on res.body */
	});

super-siren automatically registers a SIREN parser for all http requests made through super-siren. Any HTTP response which specifies a content type of application/vnd.siren+json. All other content-types will fall back to the default superagent parsers.

Setting Global Headers

super-siren allows you to set global headers for all requests made through super-siren. Super-siren will automatically add an Accepts header requesting application/vnd.siren+json, so you don't have to worry about adding that one. To add a custom header simply do the following:

let Siren = require('super-siren');

Siren.Client.addHeader('Authentication', 'Bearer ' + bearerToken);

To then later remove the header you can simply:

Siren.Client.removeHeader('Authentication');

Helpers

super-siren provides helper functions to assist with navigating through SIREN responses. This allows for using a fluent syntax to navigate from a base SIREN URL through it's available links, entities and actions.

For example if you had a base SIREN entity at http://example-siren/api and wanted to follow through a link at rel favorites and wanted to perform an action named add-favorite in order to add a favorite you could write the following:

let Siren = require('super-siren');
let follow = Siren.Helper.follow;
let performAction = Siren.Helper.performAction;

Siren.get('http://example-siren/api')
	.then(follow('favorites'))
	.then(performAction('add-favorite', { name: 'Siren' })) // the data opts are optional
	.then(res => {
		/* Process Siren action HTTP response here */
	});

SIREN structure

let Siren = require('super-siren');
Siren.get('http://example-siren/api')
	.then(res => {
		let siren = res.body;

		/* prints all classes as separate log entires*/

		siren.classes
			.forEach(class => console.log(class));

		/* prints all hrefs that have the rel 'example' */

		siren.links
			.filter(link => link.rels.contains('example'))
			.map(link => link.href)
			.forEach(href => console.log(href));


		/* prints the first rel of all sub-entities which have the
		'example' rel*/

		siren.entities
			.filter(entity => entity.rels.contains('example'))
			.forEach(entity => console.log(entity.rels.first()));


		/* prints the JS array of all classes for all embedded sub entities
		which have a rel of 'example' */

		siren.embeddedEntities
			.filter(entity => entity.rels.contains('example'))
			.map(entity => entity.entity)
			.forEach(entity => console.log(entity.classes.toJS()));

		/* prints all href locations for all linked sub-entities that have
		the rel of 'example' */

		siren.linkedEntities
			.filter(entity => entity.rels.contains('example'))
			.map(entity => entity.href)
			.forEach(href => console.log(href));

		/* performs the siren action named 'add-favorite' */

		siren.actions
			.first(action => action.name === 'add-favorite')
			.perform({
				name: 'Siren'
			})
			.then(res => {
				console.log('Submitted siren as my favorite!');
			})
			.catch(err => {
				console.log('Submitting siren as my favorite would never fail!');
			})
	});

SIREN navigation helpers

let Siren = require('super-siren');

Siren.get('http://example-siren/api')
	.then(res => {
		let siren = res.body;

		/* find the first action with the requested name. null when not found */

		siren.findActionByName('add-favorite')
			.perform({
				name: 'Siren'
			})
			.then(res => {

			});

		/* find the first link by the requested rel. null when not found */

		let href = siren.findLinkByRel('favorites').href;

		/* return all entities with the provided rel */

		siren.findEntitiesByRel('cool-stuff');

		/* same thing but only for embedded entities */

		siren.embeddedEntitiesByRel('cool-stuff');

		/* and only for linked sub-entities */

		siren.linkedEntitiesByRel('cool-stuff');
	});