JSON api normalize

A simple way to traverse datasets based on JSON API specification. Normalize is a lightweight javascript library with simple and powerful api. Has no dependencies and weighs less than 1KB.

"If you’ve ever argued with your team about the way your JSON responses should be formatted, JSON API can be your anti-bikeshedding tool." If you are new to JSON api we recommend you browse json api website and examples to familiarize yourself with specification. This library is built upon standards and conventions of JSON api and provides a simple way to traverse and retrieve all those attributes and relations.

Api and examples

Lets start with a typical JSON api formatted dataset:

            articleJsonApiData = {
                data: {
                    type: 'article',
                    id: '1',
                    attributes: {
                        title: 'JSON API paints my bikeshed!',
                        body: 'The shortest article. Ever.'
                    },
                    relationships: {
                        author: {data: {id: '42', type: 'user'}},
                        tags: [
                            {data: {id: '1', 'type': 'tag'}},
                            {data: {id: '2', 'type': 'tag'}}
                        ]
                    }
                },
                included: [{
                    type: 'user',
                    id: '42',
                    attributes: {
                        firstName: 'John',
                        lastName: 'Doe',
                    },
                    relationships: {
                        boss: {'data': {'id': '42', 'type': 'user'}},
                    }
                }, {
                    type: 'tag',
                    id: '1',
                    attributes: {
                        name: 'tag 1'
                    }
                }, {
                    type: 'tag',
                    id: '2',
                    attributes: {
                        name: 'tag 2'
                    }
                }]
            };
        

Using JSON api normalize we can retrive simple data like so:

            normalize(articleJsonApiData).get('title');
            // will return 'JSON API paints my bikeshed!

            normalize(articleJsonApiData).get('author.firstName');
            // will output 'John'

            normalize(articleJsonApiData).get(['id', 'title', 'body']);
            // will return
            // {
            //     id: '1',
            //     title: 'JSON API paints my bikeshed!',
            //     body: 'The shortest article. Ever.'
            // }

        

Next example shows how to retrieve complex dataset that can include (circular) relation data:

            normalize(testCollection).get([
                'id',
                'title',
                'body',
                'author.id',
                'author.firstName',
                'author.lastName',
                'author.boss.firstName',
                'author.boss.lastName',
                'tags.id',
                'tags.name',
            ]);

            // will return
            // {
            //     id: '1',
            //     title: 'JSON API paints my bikeshed!',
            //     body: 'The shortest article. Ever.',
            //     author: {
            //         id: '42',
            //         firstName: 'John',
            //         lastName: 'Doe',
            //         boss: {
            //             firstName: 'John',
            //             lastName: 'Doe'
            //         }
            //     },
            //     tags: [{
            //         id: '1',
            //         name: 'tag 1'
            //     }, {
            //         id: '2',
            //         name: 'tag 2'
            //     }]
            // };
        

Installation

Json api normalize is packaged as UMD library so you can use it both on client and server - in CommonJS, AMD or browser environment.

            // install via npm
            npm install json-api-normalize --save

            // if you use bundler
            var normalize = require('json-api-normalize');

            // or just using browser globals
            var normalize = window.jsonApiNormalize;
        

For browser usage browse dist folder - if working with build tools go with src folder. Download library files from github repo, get them via bower (bower install json-api-normalize) or via npm (npm install json-api-normalize)