jsonapiclient

JSON API is a nice standard that solves a lot of bikeshedding problems when designing HTTP-based APIs. However, due to its non-flat payloads, reading and manipulating JSON API structures can result in a good deal of boilerplate code. To that end, this library aims to capture the boilerplate code and make it easier to work with JSON API data.

The library exposes two concepts: Resources and Collections.

Resources

A Resource instance corresponds to a JSON API payload where data is a single item like the one found here

You can initialize a Resource instance from existing data like so:

const resource = Resource.fromObject(JSON.parse(payload));

You can also create a new Resource instance like so:

const resource = Resource.create('people', 'a1a51071-8266-40e8-8fca-bc293db66ef9');

One you have a resource instance, you have access to several methods for access and manipulating the payload's fields.

// set an attribute field
resource.set(['size', 'width'], '1080')    

// get an attribute field
resource.get(['title'])  // => 'Uluru'
resource.get(['size', 'width']) // => '1080'

// remove an attribute field
resource.unset(['size'])

// Replace payload attributes.
// TIP: This is a good way to populate an empty resource
resource.replace({
  title: 'Good Morning, Uluru',
  src: 'http://example.com/images/morning.png'
})

The full list of Resource methods is documented in the API section below.

Traversing relationships

Resources often carry information about related resources as seen in the example above. These can be easily accessed as Resource instances themselves:

const related = resource.relationship('photographer')
console.log(JSON.stringify(related.serialize(), null, 2))
// =>
// {
//   "data": {
//     "id": "ff4860a8-2b5f-4c35-9e03-27c872ff9056",
//     "type": "people"
//   }
// }

// If there are included resources in the payload, you can resolve the relationship
const resolved = resource.relationship('photographer', {resolve: true});
console.log(JSON.stringify(related.serialize(), null, 2))
// =>
// {
//   "data": {
//     "type": "people",
//     "id": "ff4860a8-2b5f-4c35-9e03-27c872ff9056",
//     "attributes": {
//       "firstName": "George",
//       "lastName": "Haidar",
//       "twitter": "ghaidar0"
//     },
//     "links": {
//       "self": "http://example.com/people/ff4860a8-2b5f-4c35-9e03-27c872ff9056"
//      }
//   }
// }

Collections

A Collection instance corresponds to a JSON API payload where data is an array of items like the one found here

You can initialize a Collection instance from existing data like so:

const collection = Collection.fromObject(JSON.parse(payload));

You can also create a new Collection instance like so:

const collection = Collection.create();

Once you have a collection instance, you can access its list of items which are presented as Resource instances:

collection.at(0).get('title') // => 'JSON API paints my bikeshed!'

There are also several methods available to manipulate the collection:

// add an item to the end
collection.push({
  type: 'article',
  id: '12',
  attributes: {
    title: 'Hello, World!'
  }
});

The full list of Collection methods is documented in the API section below.

API