Node framework agnostic JSON API serializer
JavaScript
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
src
test Fixes #7 May 30, 2016
.babelrc Move to ES6 and FP approach Jan 21, 2016
.eslintignore Move to ES6 and FP approach Jan 21, 2016
.eslintrc Move to ES6 and FP approach Jan 21, 2016
.gitignore Move to ES6 and FP approach Jan 21, 2016
.npmignore Move to ES6 and FP approach Jan 21, 2016
.travis.yml Add setup for testing with TravisCI May 30, 2016
LICENSE Fix line breaks Jan 22, 2016
README.md Add setup for testing with TravisCI May 30, 2016
package.json Increment to v2.1 May 30, 2016
spec.md Add spec Jan 23, 2016

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

// 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);
// 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.