leisure

Add hypermedia awareness to your REST services.

leisure offers:

Content Negotiation for preferred media type.
Automatically sets response Content-Type.
Work in terms of hypermedia.

Example

app.js

var express = require('express');
var leisure = require('leisure');

var mediaTypes = [
  { contentType: 'application/vnd.shop', formats: ['json', 'xml'] },
  { contentType: 'application/json' },
  { contentType: 'text/xml' }
];

var app = express.createServer();

app.use(leisure.accept(mediaTypes));

var dashboard = require('./media/dashboard');

app.get('/', function(req, res) {
  var media = dashboard.create(req.accepted);
  res.send(media);
});

app.listen(3000);

./media/dashboard.js

exports.create = function(mediaType) {
  var mediaFactory = {
    'application/vnd.shop': createDashboardMedia(mediaType.format),
    'application/json': createDashboardMedia('json'),
    'text/xml': createDashboardMedia('xml')
  };

  var media = mediaFactory[mediaType.contentType].call(this);
  return media;
};

function createDashboardMedia(format) {
    return function mediaFormat() {
      var formats = {
        'json': '{ "account": { "href":  "/account" }, "products": { "href": "/products" } }',
        'xml': '<dashboard><account href="/account" /><products href="/products" /></dashboard>'
      };

      return formats[format];
    }
}

Run

Launch the app.

$ node app.js

Set the Accept header on a curl request to http://localhost:3000.

$ curl -i -H "Accept: application/vnd.shop+json" -X GET http://localhost:3000
HTTP/1.1 200 OK
Content-Type: application/vnd.shop+json
Content-Length: 75
Connection: keep-alive

{ "account": { "href":  "/account" }, "products": { "href": "/products" } }

Voila!

Install

$ npm install leisure

Usage

leisure.accept(mediaTypes, [options])

leisure.accept is connect-compatible middleware that compares a list of accepted media types to those supported by the client via the HTTP Accept header and selects the most preferred media type available. The preferred media type is appended to the request as req.accepted. The mediaTypes parameter is required.

mediaTypes

mediaTypes is an array of acceptable media types for the request. Each media type in the array needs a contentType property with the appropriate media type and an optional formats property listing acceptable formats.

Example:

[
  { contentType: 'application/vnd.shop', formats: ['json', 'xml'] }, 
  { contentType: 'application/json' }
]

The mediaTypes array is prioritized by index. In the example above, the preference order is:

application/vnd.shop+json
application/vnd.shop+xml
application/json

options

options is a collection of options for the current middleware instance.

Example:

leisure.accept([{ contentType: 'text/xml' }], { strictMode: true });

options.strictMode

strictMode sends a 406 Not Acceptable response when no media type is matched. The default value is taken from leisure.options.strictMode.

leisure.options

Global options in leisure.

console.log(leisure.options.strictMode); // => false

leisure.setOption(key, val)

setOption sets a global option in leisure.

strictMode

When the strictMode option is true, leisure sends a 406 Not Acceptable response when there is no matching Accept value in the request. When strictMode is false, leisure will respond with the most preferable media type. The default value is false. This can be overriden for each middleware instance (see leisure.accept).

leisure.setOptions('strictMode', true);

Tests

Tests are written in mocha. To run, use:

$ npm test

License

MIT/X11

rbecheras/leisure