JSON API Mapper

JSON API Mapper (formerly Oh My JSON API) is a wrapper around @Seyz's excellent JSON API-compliant serializer, jsonapi-serializer, that removes the pain of generating the necessary options needed to serialize each of your ORM models.

Breaking Changes

This project has recently been renamed and rewritten using Typescript. While most functionality is generally the same, there have been a few deprecations and changes to how the Mapper is initialized. Please see the migration guide below.

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. JSON API Mapper handles this by dynamically analyzing your models and automatically generating the necessary 'template' to pass to the serializer.

What ORMs do you support?

Initially, we only provide a mapper for Bookshelf. However, the library can be easily extended with new mappers to support other ORMs. PR's are more than welcome!

How do I install it?

npm install jsonapi-mapper --save

How do I use it?

It's pretty simple. You only need to configure the mapper and then use it as many times you need.

import Mapper = require('jsonapi-mapper');

// Create the mapper
var mapper = new Mapper.Bookshelf('https://api.hotapp.com');

// Use the mapper to output JSON API-compliant using your ORM-provided data
return mapper.map(myData, 'appointment');

Migrating from OhMyJSONAPI

The migration process is painless:

• Remove oh-my-jsonapi from your project.

• Run npm install jsonapi-mapper --save

• Convert any instances of the constructor:

  new OhMyJSONAPI('bookshelf', 'https://api.hotapp.com');

  to

  new Mapper.Bookshelf('https://api.hotapp.com');

• Convert any instances of:

  jsonApi.toJSONAPI(myData, 'appointment');

  to

  mapper.map(myData, 'appointment');

API

new Mapper.Bookshelf(baseUrl, serializerOptions)

• (optional) baseUrl (string): the base URL to be used in all links objects returned.
• (optional) serializerOptions (string): options to be passed to the serializer. These options will override any options generated by the mapper. For more information on the raw serializer, please see the documentation here.

mapper#map(data, type, mapperOptions)

• data (object): the data object from Bookshelf (either a Model or a Collection) to be serialized.
• type (string): the type of the resource being returned. For example, if you passed in an Appointment model, your type might be appointment.
• (optional) mapperOptions (object):
  • (optional) relations (boolean | string[]): flag to disable serializing related models on the response. Alternatively, you can provide a string array to indicate the specific relations you want to serialize. By default, all relations loaded on the model are serialized (true).
  • (optional) includeRelations (boolean | string[]) (deprecated): alias option of relations option.
  • (optional) query (object): an object containing the original query parameters. these will be appended to self and pagination links. Developer Note: this is not fully implemented yet, but following releases will fix that.*
  • (optional) pagination (object): pagination-related parameters for building pagination links for collections.
    • (required) offset (integer)
    • (required) limit (integer)
    • (optional) total (integer)

How can I contribute?

The project is very open to collaboration from the public, especially on providing the groundwork for other ORM's (like Sequelize or Mongoose). Just open a PR!

The project source has been recently rewritten using Typescript, which has been proven useful for static checks and overall development.

Credits

• Thanks to @Seyz. Without his work, the project would not be possible.
• Thanks to the ZOI Travel team (especially @ShadowManu) for their hard work in migrating the codebase to Typescript and writing a comprehensive test suite.