node-jsonapi v1.1.9

node-jsonapi

This library helps you build and parse JSON response using JSON API format.

Installation

$ yarn add node-jsonapi

Initialization

const JSONApi = require('node-jsonapi');
const API = new JSONApi(options);

Options

Initialization without options

const JSONApi = require('node-jsonapi');
const API = new JSONApi();

Initialization with options

const JSONApi = require('node-jsonapi');
const API = new JSONApi({
  version: '1.0',
});

Methods

• build()
• error()
• parse()

build()

Build valid JSON API response. Return a promise.

const JSONApi = require('node-jsonapi');
const API = new JSONApi();

// Assuming this is the data from SQL
let data = [{
  id: 1,
  title: 'FOO',
  userId: 10,
  userEmail: 'foo@gmail.com',
},
{
  id: 2,
  title: 'BAR',
  userId: 12,
  userEmail: 'bar@gmail.com',
},
{
  id: 3,
  title: 'FOOBAR',
  userId: 10,
  userEmail: 'foo@gmail.com',
}];

let options = {
  type: 'post',
  data: data,
  relationships: {
    author: {
      type: 'user',
      attributes: [ 'userId', 'userEmail' ],
      id: 'userId',
      singular: true,
    },
  },
};

API.build(options)
  .then(res.json)
  .catch((err) => {
    res.status(400);
    res.json(err);
  });

Resolved object

{
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "type": "post",
      "relationships": {
        "author": {
          "data": {
            "id": 10,
            "type": "user"
          },
          "meta": {
            "singular": true
          }
        }
      },
      "id": 1,
      "attributes": {
        "title": "FOO"
      }
    },
    {
      "type": "post",
      "relationships": {
        "author": {
          "data": {
            "id": 12,
            "type": "user"
          },
          "meta": {
            "singular": true
          }
        }
      },
      "id": 2,
      "attributes": {
        "title": "BAR"
      }
    },
    {
      "type": "post",
      "relationships": {
        "author": {
          "data": {
            "id": 10,
            "type": "user"
          },
          "meta": {
            "singular": true
          }
        }
      },
      "id": 3,
      "attributes": {
        "title": "FOOBAR"
      }
    }
  ],
  "included": [
    {
      "type": "user",
      "id": 10,
      "attributes": {
        "userEmail": "foo@gmail.com"
      }
    },
    {
      "type": "user",
      "id": 12,
      "attributes": {
        "userEmail": "bar@gmail.com"
      }
    }
  ]
}

Options

Data structure

Example of single data structure

let options = {
  //...
  data: {
    id: 1,
    title: 'foo',
  },
  //...
};

Example of multiple data structure

let options = {
  //...
  data = [
    { id: 1, title: 'foo' },
    { id: 2, title: 'bar' },
  ],
  //...
};

Relationships structure (optional)

This is the relationship scheme

Example

let options = {
  //...
  relationships: {
    author: {
      type: 'user',
      attributes: [ 'userId', 'userEmail' ],
      id: 'userId',
      singular: true,
    },
  },
  //...
};

error()

Build valid JSON API error response. Return a promise.

const JSONApi = require('node-jsonapi');
const API = new JSONApi();

let errors = [{
  status: 400,
  code: 'ERR_API_SET_PROFILE',
  title: 'Failed to set author profile',
  detail: 'Missing author name',
  source: 'profiles.create'
}];

API.error(errors)
  .then(res.json)
  .catch((err) => {
    res.status(400);
    res.json(err);
  });

Resolved object

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "status": 400,
      "code": "ERR_API_SET_PROFILE",
      "title": "Failed to set author profile",
      "detail": "Missing author name",
      "source": "profiles.create"
    }
  ]
}

Errors structure

Errors is an Array of error.

Error

parse()

Parse valid JSON API response to flat plain object. Return a promise.

const JSONApi = require('node-jsonapi');
const API = new JSONApi();

const jsonData = {
  "jsonapi": {
    "version": "1.0"
  },
  "data": [
    {
      "type": "post",
      "relationships": {
        "author": {
          "data": {
            "id": 10,
            "type": "user"
          },
          "meta": {
            "singular": true
          }
        }
      },
      "id": 1,
      "attributes": {
        "title": "FOO"
      }
    },
    {
      "type": "post",
      "relationships": {
        "author": {
          "data": {
            "id": 12,
            "type": "user"
          },
          "meta": {
            "singular": true
          }
        }
      },
      "id": 2,
      "attributes": {
        "title": "BAR"
      }
    },
    {
      "type": "post",
      "relationships": {
        "author": {
          "data": {
            "id": 10,
            "type": "user"
          },
          "meta": {
            "singular": true
          }
        }
      },
      "id": 3,
      "attributes": {
        "title": "FOOBAR"
      }
    }
  ],
  "included": [
    {
      "type": "user",
      "id": 10,
      "attributes": {
        "userEmail": "foo@gmail.com"
      }
    },
    {
      "type": "user",
      "id": 12,
      "attributes": {
        "userEmail": "bar@gmail.com"
      }
    }
  ]
};

API.parse(jsonData)
  .then(res.json)
  .catch((err) => {
    res.status(400);
    res.json(err);
  });

Resolved object

{
  "data": [
    {
      "author": {
        "userId": 10,
        "userEmail": "foo@gmail.com"
      },
      "postId": 1,
      "title": "FOO"
    },
    {
      "author": {
        "userId": 12,
        "userEmail": "bar@gmail.com"
      },
      "postId": 2,
      "title": "BAR"
    },
    {
      "author": {
        "userId": 10,
        "userEmail": "foo@gmail.com"
      },
      "postId": 3,
      "title": "FOOBAR"
    }
  ]
}