Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

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.

About

Node framework agnostic JSON API serializer

Resources

License

Packages

No packages published
You can’t perform that action at this time.