jaysonapi

jaysonapi is a framework agnostic JSON API v1.0.0 serializer. jaysonapi provides more of a functional approach to serializing your data. Define a serializer with a type and schema, and call serialize on it passing in the data, included, meta, errors, etc. as a plain object.

Installation

$ npm install jaysonapi

Documentation

Overview

Serializer(type, schema, configuration)

• type: The resource type. Refering to data.type.
• schema: An object holding the information on how to serialize the data.
  • attributes: An array of attributes to keep from the data.
  • relationships: An object of defining relationships for the resource object.
    • serializer: Object|String used to serialize this relationship. Can be an object containing type and attributes, a string refering to the serializers name within the registry, or a serializer.
    • relationshipType: Function defining how the relationships are related. HasMany and BelongTo relationships are built into the library.
  • links: An object containg a self and related function.
• configuration
  • ref: The attributes to use as the reference. Defaults to 'id'.

Usage

• Basic Usage
• Compound Document Usage

export default const UserSerializer = Serializer('user', { attributes: ['name', 'email'], links: { self: data => 'http://example.com/api/user/${data.id}', } });

```javascript
// user-handler.js
import UserSerializer from './user-serializer';


// Assuming your using some MVC style library/framework and you're within a
// handler function.
handler(request, response) {
  // ... fetch user from db ...

  const userData = user.toJSON(); // Returns a object with user's attributes

  // user.toJSON() output example:
  // {
  //   id: 1,
  //   name: 'John Doe',
  //   email: '[email protected]',
  // }

  const jsonapi = UserSerializer.serialize({ data: userData });

  response(jsonapi); // Response will JSON.stringify on most frameworks.
}

// Serializer will generate
{
  data: {
    id: 1,
    type: "user",
    attributes: {
      name: "John Doe",
      email: "[email protected]"
    },
    links: {
      self: 'http://example.com/api/user/1',
    }
  }
}

export default const AccountSerializer = Serializer('account', { attributes: ['organization', 'phone'], relationships: { user: { serializer: 'User', relationshipType: Relationships.hasMany('accountId'), }, }, });

Registry.register('Account', AccountSerializer);

```javascript
// user-serializer.js
import Serializer, {
  Registry,
  Relationships,
} from 'jaysonapi';


export default const UserSerializer = Serializer('user', {
  attributes: ['name', 'email'],
  relationships: {
    account: {
      serializer: 'Account',
      relationshipType: Relationships.belongsTo('accountId'),
    },
  },
});

Registry.register('User', UserSerializer);

// user-handler.js
import UserSerializer from './user-serializer';


// Assuming your using some MVC style library/framework and you're within a
// handler function.
handler(request, response) {
  // ... fetch user from db ...

  const userData = user.toJSON(); // Returns a object with user's attributes
  const accountData = user.related('account').toJSON();
  const toSerialize = {
    data: userData,
    included: {
      account: accountData,
    },
  };
  const jsonapi = UserSerializer.serialize(toSerialize);

  response(jsonapi); // Response will JSON.stringify on most frameworks.
}

// Serializer will generate
{
  data: {
    id: 1,
    type: "user",
    attributes: {
      name: "John Doe",
      email: "[email protected]"
    },
    relationships: {
      account: {
        id: 99,
        type: 'account',
      },
    },
  },
  included: [
    {
      id: 99,
      type: 'account',
      attributes: {
        organization: 'ABC Company Co.',
        phone: '8001231234',
      }
    },
  ]
}

TODO

As of v2.0.0 jaysonapi implements the majority—if not all—of the "must" in JSON API v1.0. There are a few feature which are not yet support —they're in the works. Additionally some configuration options are being worked on. Refer to the list below, contributions are more than welcomed!

• Add more documentation to this README
• Including resources not related to the data resource.
• Inflection
• ...finish this todo list

License

jaysonapi source code is under MIT License.