json-api-normalizer

Utility to normalize JSON:API data with ease

Description

json-api-normalizer helps to processing JSON:API data into more developer-friendly form for further usage. It fully supports latest JSON:API specification including one-to-one & one-to-many relationships, so you don't need to manually format each response to work with regular resource collections. It's main feature is correct exctracting so called "sparse fieldsets" and nesting them under corresponding resource.

Installation

$ npm install @lysyi3m/json-api-normalizer

or using Yarn:

$ yarn add @lysyi3m/json-api-normalizer

Usage

import normalizer from '@lysyi3m/json-api-normalizer';

// make a request tou your API endpoint and get response

const result = normalizer(response.data);

console.log(result.data) // data is normalized resources with exctracted & nested relationships
console.log(result.meta) // meta object
console.log(result.links) // links object

Examples

Basic

Assuming endpoint /articles?include=author, your response data would be like this:

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z"
    },
    "relationships": {
      "author": {
        "data": {"id": "42", "type": "people"}
      }
    }
  }],
  "included": [
    {
      "type": "people",
      "id": "42",
      "attributes": {
        "name": "John",
        "age": 80,
        "gender": "male"
      }
    }
  ]
}

And after normalization:

{
  "data": [
    {
      "id": "1",
      "title": "JSON:API paints my bikeshed!",
      "body": "The shortest article. Ever.",
      "created": "2015-05-22T14:56:29.000Z",
      "updated": "2015-05-22T14:56:28.000Z",
      "author": {
        "id": "42",
        "name": "John",
        "age": "80",
        "gender": "male"
      }
    }
  ]
}

Complex relationships

In case one-to-one, one-to-many or nested relationships (i.e., when relationship resource has its own relationships), json-api-normalizer will proccess them at once, using matching by resource id & type altogether.

Assuming endpoint /articles?include=author,comments, your response data would be like this:

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "links": {
      "self": "http://example.com/articles/1"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "first-name": "Dan",
      "last-name": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}

And after normalization:

{
  "data":[
    {
      "id":"1",
      "links":{
        "self":"http://example.com/articles/1"
      },
      "title":"JSON:API paints my bikeshed!",
      "author":{
        "id":"9",
        "links":{
          "self":"http://example.com/people/9"
        },
        "first-name":"Dan",
        "last-name":"Gebhardt",
        "twitter":"dgeb"
      },
      "comments":[
        {
          "id":"5",
          "links":{
            "self":"http://example.com/comments/5"
          },
          "body":"First!",
        },
        {
          "id":"12",
          "links":{
            "self":"http://example.com/comments/12"
          },
          "body":"I like XML better",
          "author":{
            "id":"9",
            "links":{
              "self":"http://example.com/people/9"
            },
            "first-name":"Dan",
            "last-name":"Gebhardt",
            "twitter":"dgeb"
          }
        }
      ]
    }
  ],
}

Available options

Camelize

By default json-api-normalizer does not transform data keys. If camelize option is set to true all keys will be converted to camelCase.