simple-json-api

Simple JSON API

Simple JSON API is a simple, to-the-point library to create JSON API responses that are compliant with the JSON API standard.

Getting Started

Creating a basic JSON API response is very simple:

var JsonAPIResponse = require('simple-json-api');
response.addData('documents')
    .id({'AsFaj2K41ks7'})
    .attribute({title: 'Report on Organic Farming'})
    .attribute({author: 'Timothy B Smith'})
    .link({self: 'example.com/docs/AsFaj2K41ks7'});
console.log(response.toJSON());

This code prints out the following JSON API compliant response:

{
    data: [
        {
            type: 'documents',
            id: 'AsFaj2K41ks7',
            attributes: {
                title: 'Report on Organic Farming',
                author: 'Timothy B Smith'
            }
            links: {
                self: 'example.com/docs/AsFaj2K41ks7'
            }
        }
    ]
}

Usage

According to the JSON API standard, a response can have multiple different fields. At the moment this library only supports having data and error objects.

Creating a Response

Creating a response is done by simply calling the constructor. To get the JSON representation, call toJSON() on the response object.

Example:

var JsonAPIResponse = require('simple-json-api');
let response = new JsonAPIResponse();
console.log(response.toJSON());

Output:

{
}

Note that the response object is empty as no data items have been added..

Adding a data item

You can add a data item by calling addData(type: String) on the response object. Note that according to the JSON API spec, the type should be a pluralistic noun.

Example

response.addData('users');
console.log(response.toJSON());

Output:

{
    data: [
        {
            type: 'users'
        }
    ]
}

Adding information to data items

The JSON API spec specifies a few fields that a data item can have, but at this time this library only supports id, attributes and links.

Adding an ID

Adding an ID is done through the .id(id) function. Repeatedly calling this function overrides the previous ID.

Example:

var JsonAPIResponse = require('simple-json-api');
let response = new JsonAPIResponse();
response.addData('users')
    .id({'1256789uuid'});
console.log(response.toJSON());

Output:

{
    data: [
        {
            type: 'users',
            id: '1256789uuid'
        }
    ]
}

Adding attributes

Adding attributes is done through the .attribute({key: value}) function. Multiple key-value pairs can be specified in one .attribute() call.

Example:

response.addData('users')
    .attribute({username: 'Timothy'})
    .attribute({password: 'hashedpw'});
console.log(response.toJSON());

Output:

{
    data: [
        {
            type: 'users',
            attributes: {
                username: 'timothy',
                password: 'hashedpw'
            }
        }
    ]
}

Adding links

Adding links is done through the .link({key: value}) function. Multiple key-value pairs can be specified in one .link() call.

Example:

response.addData('users')
    .link({self: 'example.com/users/1256789uuid'});
console.log(response.toJSON());

Output:

{
    data: [
        {
            type: 'users',
            links: {
                self: '1256789uuid'
            }
        }
    ]
}

Adding multiple data items

Data items can be appended by repeatedly calling addData() on the response object.

Example:

response.addData('users')
    .id({'1256789uuid'})
    .attribute({username: 'Timothy'})
    .attribute({password: 'hashedpw'})
    .link({self: 'example.com/users/1256789uuid'});
response.addData('users')
    .id({'abcdefguuid'})
    .attribute({username: 'Samantha'})
    .attribute({password: 'anotherhashedpw'})
    .link({self: 'example.com/users/abcdefguuid'});
console.log(response.toJSON());

Output:

{
    data: [
        {
            type: 'users',
            id: '1256789uuid',
            attributes: {
                username: 'Timothy',
                password: 'hashedpw'
            }
            links: {
                self: 'example.com/users/1256789uuid'
            }
        },
        {
            type: 'users',
            id: 'abcdefguuid',
            attributes: {
                username: 'Samantha',
                password: 'anotherhashedpw'
            }
            links: {
                self: 'example.com/users/abcdefguuid'
            }
        }
    ]
}

Adding an Error

Errors can be added by calling addError() on a response object.

response.addError();

Status, Title and Details

Status, title and detailed information can be added through status(), title(), and detail() respectively:

response.addError()
    .status('404')
    .title('Not Found')
    .detail('The resource you are looking for was not available');

This will generate the following response

{
    errors: [
        {
            status: '404',
            title: 'Not Found',
            detail: 'The resource you are looking for was not available'
        }
    ]
}

As with data items, multiple errors can be added to a single response object.