Skip to content
Go to file


Failed to load latest commit information.
Latest commit message
Commit time

Build Status Version HitCount Downloads Size MIT


A convenient module to consume a jsonapi service


$ npm install --save @itsfadnis/jsonapi-client


$ yarn add @itsfadnis/jsonapi-client

Basic usage


Configure the client's http adapter. The options are as defined below:

Name Description Default value
host (string) Server host address ''
namespace (string) API namespace (if any) ''
headers (object) Request headers {}
  • For versions 3.0.0 & above:
import Model from '@itsfadnis/jsonapi-client';

  host: '',
  namespace: '/api',
  headers: {
    authorization: 'Basic YWxhZGRpbjpvcGVuc2VzYW1l'
  • For versions below 3.0.0:
import { HttpAdapter, Model } from '@itsfadnis/jsonapi-client';

Model.adapter = new HttpAdapter({
  host: '',
  namespace: '/api',
  headers: { authorization: 'Basic YWxhZGRpbjpvcGVuc2VzYW1l' },
  // The adapter uses the Fetch API for making network requests
  // You can pass it in as an option, else it will default to window.fetch
  fetch: window.fetch

How serialization/deserialization works

@itsfadnis/jsonapi-client internally uses jsonapi-serializer for serializing/deserializing data to JSON API (1.0 compliant)

Models serialize themselves before making a request, and deserialize the recieved response into instances of the Model. This abstraction allows yours models to talk to a jsonapi service seamlessly without having to worry about the serialization/deserialization business.

In any case if you want finer control, it can be done by overriding some defaults.

Default serializer options are defined in the Model#serializerOptions() method, to override/customize them you can override this method on your model.

Default deserializer options are defined on the static property Model.deserializerOptions, to override/customize them you can override this property.

Available options

Model definition

From v2.0.1, it is mandatory for a model to have _type defined as a static property. Model._type is used to describe the type of resource objects.

class Address extends Model {
  static _type = 'addresses';

  // Always set the base url of your resource on this property
  static baseURL = '/addresses';

  constructor(args = {}) {
    this.type = args.type;
    this.street = args.street; =;

class DriversLicense extends Model {
  static _type = 'drivers-license';

  // Specify url parameters for nested resources
  static baseURL = '/people/:person_id/drivers_license';

  constructor(args = {}) {
    this.licenseNumber = args.licenseNumber;

    // Drivers license belongs to person
    this.person = this.belongsTo(Person, args.person);

  // Resolve base url for nested resources in the #contructBaseURL() method
  constructBaseURL() {
    return this.constructor.constructBaseURL({

class Person extends Model {
  static _type = 'people';

  static baseURL = '/people';

  constructor(args = {}) {
    this.firstName = args.firstName || '';
    this.lastName = args.lastName;

    // Person has many addresses
    this.addresses = this.hasMany(Address, args.addresses);

    // Person has one drivers license
    this.driversLicense = this.hasOne(DriversLicense, args.driversLicense);

Standard CRUD APIs

class Post extends Model {
  static _type = 'posts';

  static baseURL = '/posts';

  constructor(args) {
    this.title = args.title;
    this.body = args.body;
  • Fetch posts
  • Fetch a single Post
  • Create/update post
// New record (if no `id` provided)
const p1 = new Post({
  title: 'foo',
  body: 'bar'

// Will make a `POST` request on save;

// Treated as persisted record since `id` provided
const p2 = new Post({
  id: 1,
  title: 'boo',
  body: 'baz'

// Will make a `PATCH` request on `save`;
  • Delete a post
// Static method

// Instance method
const p = new Post({
  id: 1


📝 License

Copyright © 2020 Nikhil Fadnis.
This project is MIT licensed.

You can’t perform that action at this time.