Node framework agnostic JSON API serializer
Switch branches/tags
Clone or download
digia Merge pull request #12 from chrismatheson/patch-1
fixing markdown rendering of examples
Latest commit 7e978fe Jun 18, 2018

README.md

jaysonapi

Build Status

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

Example 1: Basic Usage

// user-serializer.js
import Serializer from 'jaysonapi';

export default const UserSerializer = Serializer('user', {
  attributes: ['name', 'email'],
  links: {
    self: data => 'http://example.com/api/user/${data.id}',
  }
});
// 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: 'jdoe@example.com',
  // }

  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: "jdoe@example.com"
    },
    links: {
      self: 'http://example.com/api/user/1',
    }
  }
}
#### Example 2: Compound Document Usage ```javascript // account-serializer.js import Serializer, { Registry, Relationships, } from 'jaysonapi';

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: "jdoe@example.com"
    },
    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.