JSON API Reader

A simple reader for json:api conformant APIs.

What is it?

This is a small package (~2KB) that focuses on reading records and their relationships from a succesful JSON:API response.

It is good for rapid prototyping and for use with JS frameworks like Vue, React etc.

If you're looking for something more advanced that can handle fetching data, paginating results etc. then there are other more sophisticated JSON:API client implementations available. You may still find this package useful when it comes to actually consuming the records in the response though.

A Quick Example

BEFORE: Sample JSON:API Response

Many advantages but tough on the eyeballs.

AFTER: Only records and relationships.

Simple to navigate.

The processed response is immediately much easier to work with in UI frameworks:

<!-- A Vue JS example looping through articles and comments -->
<div v-for="article in articles" :key="article.id">
    <h1>{{ article.title }}</h1>
    <h2>Comments</h2>
    <div v-if="article.comments.length > 0">
        <p v-for="comment in article.comments" :key="comment.id" >
            <small>{{ comment.author.first_name }} said:</small>
            <br>
            <span>{{ comment.body }} </span>
        </p>
    </div>
    <p v-else>No comments yet.</p>
</div>

Installation

Using npm

npm install --save json-api-reader

Using a CDN link from jsdelivr.
Recommended: Go to the package page on jsdelivr, identify the latest version and get a script tag with its SRI hash for that specific version when you get started.

<!-- WARNING: The link below always points to the LATEST version -->
<!-- (go to jsdelivr and get a link for the specific version you want) -->
<script src="https://cdn.jsdelivr.net/npm/json-api-reader@latest/dist/umd/json-api-reader.js"></script>

You can also download the above JS and host it yourself.

Basic Usage

// Assume a list of blog posts is fetched via the browser's native fetch method:
const response = await fetch('https://example.com/blog/posts.json?include=author,comments');
const json = await response.json();

// Create a reader to process the json response
const reader = new JsonApiReader();
const posts = reader.parse(json);

// Now loop through the data from the response in a sane way.
// Each record has all its data merged into a simple object.
posts.forEach(post => {
    // Attributes:
    const id = post.id;
    const title = post.title;
    // Relationships:
    const author = post.author;
    const comments = post.comments;
});

Using Transformers

Transformers allow you to modify objects before they are returned.

This allows you to do things like:

Convert string IDs into integers
Convert date strings to objects using your chosen date package
Deal with any property/relationship naming conflicts
Add convenient properties to an object
Etc.

// Let's pick up once we have a successful JSON:API response.
const json = await getSuccessfulJsonApiResponse();

// Create a reader to process the json response.
const reader = new JsonApiReader();

// Here you can set a simple callback function as a transformer.
// The callback receives an object which has already had all
// data merged into it as if no transformer was specified.
reader.setTransformer('comments', comment => {
    comment.word_count = typeof comment.body === 'string'
        ? comment.body.split(' ').length
        : 0;
});

// Alternatively, you can use an object with a transform method:
const myPeopleTransformer = {
    transform(person) {
        const modified = Object.assign(
            {},
            person,
            {
                id: parseInt(person.id, 10), // We want the id values as integers
                fullName: `${person.firstName} ${person.lastName}`.trim(), // We want a convenient full name property.
            }
        );
        return modified;
    }
}

// The above transformer is for objects with { type: people } in JSON:API structure.
reader.setTransformer('people', myPeopleTransformer);

// The parser will now apply myPeopleTransformer when it encounters "people".
const posts = reader.parse(json);

A person transformed by the above transformer would then look something like this:

{
  id: 2, // converted to int by transformer
  firstName: 'Bob', // left alone
  lastName: 'Fakeman', // left alone
  twitter: 'fake', // left alone
  fullName: 'Bob Fakeman', // added by transformer
}