@zoi/oh-my-jsonapi

OhMyJSONAPI

OhMyJSONAPI is a wrapper around @Seyz's excellent JSON API 1.0-compliant serializer, jsonapi-serializer, that removes the pain of generating the necessary serializer options for each of your models.

how does it work?

A serializer requires some sort of 'template' to understand how to convert what you're passing in to whatever you want to come out. When you're dealing with an ORM, such as Bookshelf, it would be a real pain to have to generate the 'template' for every one of your Bookshelf models in order to convert them to JSON API. OhMyJSONAPI handles this by dynamically analyzing your models and generating the necessary 'template' to pass to the serializer.

what ORMs do you support?

Initially, only Bookshelf. However, the library can be easily extended with new adapters to support other ORMs. PR's are welcome!

how do I install it?

npm install oh-my-jsonapi --save

how do I use it?

It's pretty simple:

// create a new instance
var jsonApi = new OhMyJSONAPI('bookshelf', 'https://api.hotapp.com');

// use that instance to output JSON API-compliant JSON using your data
return jsonApi.toJSONAPI(myData, 'appointment');

api

OhMyJSONAPI(adapter, baseUrl, serializerOptions)

• (optional) adapter (string): the adapter to use for transforming your data(see supported ORMs). Passing null will provide access to the raw serializer. For more information on the raw serializer, please see the documentation here.
• (optional) baseUrl (string): the base URL to be used in all links objects returned.
• (optional) serializerOptions (object): options to be passed the serializer. See available options here.

OhMyJSONAPI#toJSONAPI(data, type, options)

• data (object): the data to be serialized. Note that this expected to be data from your ORM. For example, when using the bookshelf adapter, it would expect this to be an instance of Bookshelf.Model or Bookshelf.Collection. If you passed null to the constructor, you can pass raw JSON since you would then be accessing the raw serializer.
• type (string): the type of the resource being returned. For example, if you passed in an Appointment model, your type might be appointment.
• (optional) options (object):
  • (optional) includeRelations (boolean): override the default setting for including relations. By default, the serializer will include all relationship data in the response. If you'd like to lazy-load your relationships on a case-by-case basis, you can use this flag to override the default.
  • (optional) query (object): an object containing the original query parameters. these will be appended to self and pagination links.
  • (optional) pagination (object): pagination-related parameters for building pagination links for collections.
    • (required) offset (integer)
    • (required) limit (integer)
    • (optional) total (integer)

credits

• Thanks to @Seyz. Without his work, the project would not be possible.