# oh-my-jsonapi

**Repository Path**: mirrors_marcelklehr/oh-my-jsonapi

## Basic Information

- **Project Name**: oh-my-jsonapi
- **Description**: JSON API-Compliant Serialization for your Node ORM
- **Primary Language**: Unknown
- **License**: Unlicense
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-09-25
- **Last Updated**: 2026-07-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JSON API Mapper
JSONAPI Mapper is a wrapper around @Seyz's excellent [JSON API 1.0](http://jsonapi.org/)-compliant serializer, [jsonapi-serializer](https://github.com/SeyZ/jsonapi-serializer), that removes the pain of generating the necessary serializer options for each of your ORM 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](https://github.com/tgriesser/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](https://github.com/tgriesser/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.

```javascript
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');
```

## API
```javascript
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](https://github.com/SeyZ/jsonapi-serializer#documentation).

```javascript
mapper#toJSONAPI(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.
  - _(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 collaborations from the public, especially on providing the groundworks for other ORM's (like [Sequelize](http://docs.sequelizejs.com/) or [Mongoose](http://mongoosejs.com/)). Just open PR for new code or issues for ideas or notifying bugs. The project sources have been recently rewritten on [Typescript](http://www.typescriptlang.org/) and has been proven useful for static checks and overall development.

# Credits
- Thanks to @Seyz. Without his work, the project would not be possible.