jsonapify

jsonapify is a library to assist the development of JSON-API compatible APIs with NodeJS.

Why jsonapify?

• Simple: jsonapify is designed around simplicity. Easy things are easy to do, hard things are possible. If you feel something can be made simpler, by all means file an issue!
• Unintrusive: ExpressJS, Restify, Connect,... No matter, jsonapify integrates nicely.
• Interoperable: By offering a common-interface across your APIs, jsonapify lets your users build great things on top of them. If you don't know yet about the JSON-API specification, you should read about it and all the oportunities it has to offer.
• Well tested: jsonapify is designed from the start with unit testing in mind. Reliability is at the core of what we do.

Declaring resources

jsonapify detaches mongoose models from the actual representation of the resources. This allows for a lot of flexibility: as a matter of fact, declaring a non-readable field is this elegant:

var User = require('../models/User');

var userResource = new jsonapify.Resource(User, {
    type: 'users',
    id: new jsonapify.Property('_id'),
    attributes: {
        email: new jsonapify.Property('email'),
        password: {
            value: new jsonapify.Property('password'),
            readable: false,
        },
    },
});

ES6 in action

This is how the previous example would look in ES6:

import {Resource, Property} from 'jsonapify';
import User from '../models';

const userResource = new Resource(User, {
    type: 'users',
    id: new Property('_id'),
    attributes: {
        email: new Property('email'),
        password: {
            value: new Property('password'),
            readable: false,
        },
    },
});

Navigating resources

HATEOAS is one of the most important principles of the REST phylosophy. jsonapify makes interconnecting your resources a piece of cake:

var User = require('../models/User');

var userResource = new jsonapify.Resource(User, {
    type: 'users',
    id: new jsonapify.Property('_id'),
    links: {
        self: {
            value: new jsonapify.Template('/users/${_id}'),
            writable: false,
        },
    },
});

Linking resources

As someone said, "nobody is an island". Resources are not islands either. Linking resources in jsonapify is as easy as you'd expect:

var User = require('../models/User');
var roleResource = require('./roles').resource;

var userResource = new jsonapify.Resource(User, {
    type: 'users',
    id: new jsonapify.Property('_id'),
    relationships: {
        role: new jsonapify.Ref(roleResource, 'role'),
    },
});

Exposing resources

We all know about DRY. But then, why do we keep writing the same endpoint boilerplate again and again? jsonapify offers all CRUD operations as connect-compatible middleware. That means plugging a new endpoint is as simple as it gets:

app.get('/users/', [
    jsonapify.enumerate(userResource),
    jsonapify.errorHandler()
]);

Transaction filters

In addition to all of the above, jsonapify also offers transaction filters. These filters enable per-request functionality, such as pagination, sparse-fields, sorting... The most common transaction filters are enabled by default, so you don't have to worry.

Credits

This library wouldn't have been possible without all the great work by the people of the JSON-API specification. Thank you guys, you're awesome!