@itsfadnis/jsonapi-client

A convenient module to consume a jsonapi service

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
361Jun 9, 2021Mar 15, 2018Minified + gzip package size for @itsfadnis/jsonapi-client in KB

Readme

Build Status Version HitCount Downloads Size MIT

jsonapi-client

A convenient module to consume a jsonapi service

Install

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

or

$ yarn add @itsfadnis/jsonapi-client

Basic usage

Configure

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: ```javascript import Model from '@itsfadnis/jsonapi-client';

Model.configureAdapter({ host: 'https://example.com', namespace: '/api', headers: { authorization: 'Basic YWxhZGRpbjpvcGVuc2VzYW1l' } })


- For versions below `3.0.0`:
```javascript
import { HttpAdapter, Model } from '@itsfadnis/jsonapi-client';

Model.adapter = new HttpAdapter({
  host: 'https://foo.com',
  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 = {}) {
    super(args);
    this.type = args.type;
    this.street = args.street;
    this.zip = args.zip;
  }
}

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

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

  constructor(args = {}) {
    super(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({
      person_id: this.person.id
    });
  }
}

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

  static baseURL = '/people';

  constructor(args = {}) {
    super(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) {
    super(args);
    this.title = args.title;
    this.body = args.body;
  }
}
  • Fetch posts

    Post.fetchAll();
    
  • Fetch a single Post

    Post.fetch(id);
    
  • Create/update post ```javascript // New record (if no id provided) const p1 = new Post({ title: 'foo', body: 'bar' });

// Will make a POST request on save p1.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 p2.save();


- Delete a post
```javascript
// Static method
Post.destroy(id)


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

p.destroy();

📝 License

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

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.