JSON API Reader

A simple reader for json:api conformant APIs.

What is it?

A small package (~2KB) that reads the data from a succesful JSON:API response and makes it available in a format that is easier to deal with.

If you're looking for something 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 navigating 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: Find the package on jsdelivr (should eventually be here), identify the version that you want and get a script tag with its SRI hash for that specific version when you get started.

<!-- Try out the LATEST version (DEVELOPMENT ONLY) -->
<script src="https://cdn.jsdelivr.net/npm/json-api-reader@latest/dist/umd/json-api-reader.js"></script>

<!-- Or use a specific version like 1.0.0 -->
<script src="https://cdn.jsdelivr.net/npm/json-api-reader@1.0.0/dist/umd/json-api-reader.js" integrity="sha256-BoyvGQ2AByYGt/+zRykrqragtl3Ky2S5vM0cnpsFpCE=" crossorigin="anonymous"></script>

<!-- Or use the latest in a specific release (here it's 1.x) -->
<script src="https://cdn.jsdelivr.net/npm/json-api-reader@1/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;
    return comment;
});

// 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
}