1:# json-api-serializer
3:[![Build Status](https://travis-ci.org/danivek/json-api-serializer.svg?branch=master)](https://travis-ci.org/danivek/json-api-serializer)
4:[![Coverage Status](https://coveralls.io/repos/github/danivek/json-api-serializer/badge.svg?branch=master)](https://coveralls.io/github/danivek/json-api-serializer?branch=master)
5:[![npm](https://img.shields.io/npm/v/json-api-serializer.svg)](https://www.npmjs.org/package/json-api-serializer)
7:A Node.js/browser framework agnostic library for serializing your data to [JSON API](http://jsonapi.org/) compliant responses (a specification for building APIs in JSON).
12:npm install --save json-api-serializer
20:var JSONAPISerializer = require("json-api-serializer");
30:* **jsonapiObject** (optional): Enable/Disable [JSON API Object](http://jsonapi.org/format/#document-jsonapi-object). Default = true.
43:* **relationships** (optional): An object defining some relationships
44:  * relationship: The property in data to use as a relationship
45:    * **type**: A _string_ or a _function_ `function(relationshipData, data) { ... }` for the type to use for serializing the relationship (type need to be register).
46:    * **alternativeKey** (optional): An alternative key (string or path) to use if relationship key not exist (example: 'author_id' as an alternative key for 'author' relationship). See [issue #12](https://github.com/danivek/json-api-serializer/issues/12).
47:    * **schema** (optional): A custom schema for serializing the relationship. If no schema define, it use the default one.
48:    * **links** (optional): Describes the links for the relationship. It can be:
51:    * **meta** (optional): Describes meta that contains non-standard meta-information about the relationship. It can be:
54:    * **deserialize** (optional): Describes the function which should be used to deserialize a related property which is not included in the JSON:API document. It should be:
55:      * A _function_ with one argument `function(data) { ... }`which defines the format to which a relation should be deserialized. By default, the ID of the related object is returned, which would be equal to `function(data) {return data.id}`. See [issue #65](https://github.com/danivek/json-api-serializer/issues/65).
62:* **blacklistOnDeserialize** (optional): An array of blacklisted attributes. Default = [].
63:* **whitelistOnDeserialize** (optional): An array of whitelisted attributes. Default = [].
64:* **afterDeserialize** (optional): A _function_ with one argument `afterDeserialize(data) => newData` to transform data after deserialization.
73:var JSONAPISerializer = require("json-api-serializer");
90:    title: "JSON API paints my bikeshed!",
134:var JSONAPISerializer = require("json-api-serializer");
148:  relationships: {
149:    // An object defining some relationships.
155:          self: "/articles/" + data.id + "/relationships/author",
216:const result = Serializer.serialize('article', data, {count: 2});
219:Serializer.serializeAsync('article', data, {count: 2})
243:      "title": "JSON API paints my bikeshed!",
247:    "relationships": {
254:          "self": "/articles/1/relationships/author",
296:  "included": [{
332:property from the serialized object. This can be used in cases where you may
339:const result = Serializer.serialize('article', data, 'default', {count: 2}, true);
342:Serializer.serializeAsync('article', data, 'default', {count: 2}, true)
350:On each individual call to `serialize` or `serializeAsync`, there is an parameter to override the options of any registered type. For example on a call to serialize, if a whitelist was not defined on the registered schema options, a whitelist (or any other options) for that type can be provided. This parameter is an object, where the key are the registered type names, and the values are the objects to override the registered schema.
352:In the following example, only the attribute `name` will be serialized on the article, and if there is a relationship for `person`, it will be serialized with `camelCase` even if the registered schema has a different value.
354:const result = Serializer.serialize('article', data, 'default', {count: 2}, true), {
365:Some others examples are available in [tests folders](https://github.com/danivek/json-api-serializer/blob/master/test/)
367:### Deserialize
377:      title: 'JSON API paints my bikeshed!',
381:    relationships: {
402:Serializer.deserialize('article', data);
405:Serializer.deserializeAsync('article', data)
414:  "title": "JSON API paints my bikeshed!",
425:### serializeError
427:Serializes any error into a JSON API error document.
431:  - A [JSON API error object](http://jsonapi.org/format/#error-objects) or an array of [JSON API error objects](http://jsonapi.org/format/#error-objects).
436:const error = new Error('An error occurred');
437:error.id = 123
438:error.links = { about: 'https://example.com/errors/123' }
439:error.status = 500; // or `statusCode`
440:error.code = 'xyz'
441:error.meta = { time: Date.now() }
443:Serializer.serializeError(error);
450:  "errors": [
454:        "about": "https://example.com/errors/123"
459:      "detail": "An error occurred",
476:      about: 'https://example.com/errors/123'
486:Serializer.serializeError(new MyCustomError());
493:  "errors": [
497:        "about": "https://example.com/errors/123"
514:Serializer.serializeError({
517:    about: 'https://example.com/errors/123'
533:  "errors": [
537:        "about": "https://example.com/errors/123"
559:Then you can apply this schema on the primary data when serialize or deserialize :
562:Serializer.serialize("article", data, "customSchema", { count: 2 });
563:Serializer.serializeAsync("article", data, "customSchema", { count: 2 });
564:Serializer.deserialize("article", jsonapiData, "customSchema");
565:Serializer.deserializeAsync("article", jsonapiData, "customSchema");
568:Or if you want to apply this schema on a relationship data, define this schema on relationships options with the key `schema` :
573:relationships: {
585:If your data contains one or multiple objects of different types, it's possible to define a configuration object instead of the type-string as the first argument of `serialize` and `serializeAsync` with these options:
588:* **jsonapiObject** (optional): Enable/Disable [JSON API Object](http://jsonapi.org/format/#document-jsonapi-object). Default = true.
604:Serializer.serializeAsync(typeConfig, data, { count: 2 }).then(result => {
609:### Deserialize
611:If your data contains one or multiple objects of different types, it's possible to define a configuration object instead of the type-string as the first argument of `deserialize` with these options:
623:const deserialized = Serializer.deserializeAsync(typeConfig, data).then(result => {
630:If your data requires some specific transformations, those can be applied using `beforeSerialize` and `afterDeserialize`
