Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit

* fixed an issue where a record that is see twice, ends up with an _attributes array that has all values duplicated
* added test case for attribute duplication issue

Git stats


Failed to load latest commit information.
Latest commit message
Commit time
November 11, 2016 14:20
November 11, 2016 14:20
November 11, 2016 14:20
August 30, 2015 16:04
September 12, 2015 12:51
August 16, 2015 22:07
March 10, 2016 18:18
March 10, 2016 18:18
September 25, 2015 10:52
March 10, 2016 18:18


Build Status

JavaScript client-side JSON API data handling made easy.

Current version is v0.4.0-beta. It is still a work in progress, but should do what it says.


The JSONAPI standard is great for exchanging data (which is its purpose), but the format is not ideal to work directly with in an application. jsonapi-datastore is a JavaScript framework-agnostic library (but an AngularJS version is provided for convenience) that takes away the burden of handling JSONAPI data on the client side.

What it does:

  • read JSONAPI payloads,
  • rebuild the underlying data graph,
  • allows you to query models and access their relationships directly,
  • create new models,
  • serialize models for creation/update.

What it does not do:

  • make requests to your API. You design your endpoints URLs, the way you handle authentication, caching, etc. is totally up to you.


Install jsonapi-datastore with bower by running:

$ bower install jsonapi-datastore

or with npm by running:

$ npm install jsonapi-datastore

Parsing data

Just call the .sync() method of your store.

var store = new JsonApiDataStore();

This parses the data and incorporates it in the store, taking care of already existing records (by updating them) and relationships.

Parsing with meta data

If you have meta data in your payload use the .syncWithMeta method of your store.

var store = new JsonApiDataStore();

This does everything that .sync() does, but returns an object with data and meta split.

Retrieving models

Just call the .find(type, id) method of your store.

var article = store.find('article', 123);

or call the .findAll(type) method of your store to get all the models of that type.

var articles = store.findAll('article');

All the attributes and relationships are accessible through the model as object properties.


In case a related resource has not been fetched yet (either as a primary resource or as an included resource), the corresponding property on the model will contain only the type and id (and the ._placeHolder property will be set to true). However, the models are updated in place, so you can fetch a related resource later, and your data will remain consistent.

Serializing data

Just call the .serialize() method on the model.



// Create a store:
var store = new JsonApiDataStore();

// Then, given the following payload, containing two `articles`, with a related `user` who is the author of both:
var payload = {
  data: [{
    type: 'article',
    id: 1337,
    attributes: {
      title: 'Cool article'
    relationships: {
      author: {
        data: {
          type: 'user',
          id: 1
  }, {
    type: 'article',
    id: 300,
    attributes: {
      title: 'Even cooler article'
    relationships: {
      author: {
        data: {
          type: 'user',
          id: 1

// we can sync it:
var articles = store.sync(payload);

// which will return the list of synced articles.

// Later, we can retrieve one of those:
var article = store.find('article', 1337);

// If the author resource has not been synced yet, we can only access its id and its type:
// { id: 1, _type: 'article' }

// If we do sync the author resource later:
var authorPayload = {
  data: {
    type: 'user',
    id: 1,
    attributes: {
      name: 'Lucas'


// we can then access the author's name through our old `article` reference:
// 'Lucas'

// We can also serialize any whole model in a JSONAPI-compliant way:
// ...
// or just a subset of its attributes/relationships:
console.log(article.serialize({ attributes: ['title'], relationships: []}));
// ...



What's missing

Currently, the store does not handle links attributes or resource-level or relationship-level meta.



jsonapi-datastore is bundled with an AngularJs wrapper. Just include ng-jsonapi-datastore.js in your index.html and require the module beauby.jsonApiDataStore in your application. You can then use the JsonApiDataStore factory, which is essentially defined as follows:

  store: new JsonApiDataStore(),
  Model: JsonApiDataStoreModel

so that you can use it as follows:

  .controller('myController', function(JsonApiDataStore) {
    var article ='article', 1337);
    var newArticle = new JsonApiDataStore.Model('article');
    newArticle.setAttribute('title', 'My cool article');


All pull-requests welcome!


JavaScript client-side JSON API data handling made easy.








No packages published