jsonapiclient v0.2.0
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.