JSON api resource
Query and transform datasets based on JSON API specification. Lightweight library that runs both in browser and server environment. Weighs less than 3KB.
Although JSON api specification provides elegant and standard way of representing resources with JSON - consuming those datasets oftentimes can be cumbersome.
Nested relation data is especially tricky to transform to format better suited for common templating or state management patterns. This library provides simple yet powerful query engine to transform JSON api dataset to format of your liking.
By utilizing library model and collection classes you can easily query and manipulate datasets. Models can be altered and easily synchronized with server (with use of http mixin loaded separately).
Features
- query and alter dataset attribute and relation values
- normalize data to custom schema format
- manipulate and create resources with extend-able model and collection utilities
Features with http mixin enabled
- retrieve JSON api models and collections from server
- persist new, changed and deleted models
- update subset of resource attribute or relation data
- handle file uploads alongside JSON data payload
Basic usage
// install via npmnpm install json-api-resource --save
// require modulevar Model = Model; // create dataset modelconst model = jsonApiData; // get attributemodel; // get attribute from related entitymodel;
Examples and api
Example JSON api formatted dataset for "article" resource is shown bellow.
const articleData = data: type: 'article' id: '1' attributes: title: 'Test article' body: 'The shortest article. Ever.' relationships: author: data: id: '42' type: 'user' publisher: data: id: '24' type: 'user' tags: data: id: '1' 'type': 'tag' id: '2' 'type': 'tag' included: type: 'user' id: '42' attributes: firstName: 'John' lastName: 'Doe' relationships: boss: 'data': 'id': '42' 'type': 'user' type: 'tag' id: '1' attributes: name: 'tag 1' type: 'tag' id: '2' attributes: name: 'tag 2' ;
Query and normalize data
Retrive simple data like so:
articleData;// will return 'Test article Model;// will output 'John' Model;// will return id: '1' title: 'Test article' body: 'The shortest article. Ever.'
Normalize dataset to more complex schema:
Model; // will return id: '1' title: 'Test article' titleCaps: 'TEST ARTICLE' body: 'The shortest article. Ever.' author: id: '42' firstName: 'John' lastName: 'Doe' boss: firstName: 'John' lastName: 'Doe' tags: id: '1' name: 'tag 1' id: '2' name: 'tag 2' ;
Working with collections
Collections can be normalized to schema via identical api. Standard array methods ('forEach', 'map', 'filter', 'reduce', 'slice') are implemented on all collection objects.
// import collectionvar Collection = Collectionvar collection = articleData; collection;// will return ['Test article'] collection;// will return [{title: 'Test article'}] collection;// will return id: '1' title: 'Test article' body: 'The shortest article. Ever.' collection;// will return ['Test article'] collection;// returns array of models which satisfy query above collection;// returns first found model collection;// add model to collection collection;// remove model to collection
HTTP mixin
Http mixin gives your models and collections a way to talk to your server. Using straightforward api models and collections can be conveniently retrieved from and persisted to server.
Any http library (axios, $.ajax or something else) can be used for server communication. Example mixin configuration for jQuery is shown bellow:
var Model = Model;var Collection = Collection;var httpMixin = ; ;
Retrieving models
// Using callback apiModel; // Using promises apiModel; // other waysModel;Model;
Retrieving collections
// Using callback apiCollection; // Using promises apiCollection;
Installation
Library can be used in browser and node server environment.
// install via npmnpm install json-api-resource --save // if using bundler or node servervar resource = ;var Model = resourceModel;var Collection = resourceCollection; // or just using browser globalsvar resource = windowjsonApiResource;