Series: Introduction to Ember Data 2.0

JSON API

Published on Apr 15, 2016

JSON API is how Ember Data 2.0 stores data internally. Understanding it will help you debug your Ember Data code and give you the base of understanding needed for customizing the JSONAPIAdapter and JSONAPISerializer.

This tutorial concentrates on the parts of JSONAPI most relevant to Ember Data.


Links

Code

Example JSON API payload:

{
  "data": {
    "type": "quotes",
    "id": "7",
    "attributes": {
      "body": "The Party intellectual knows in which direction his memories must be altered;/he therefore knows that he is playing tricks with reality;/but by the exercise of doublethink he also satisfies himself that reality is not violated."
    },
    "relationships": {
      "book": {
        "data": {
          "type": "books",
          "id": "3"
        }
      }
    }
  },
  "included": [
    {
      "type": "books",
      "id": "3",
      "attributes": {
        "title": "1984",
        "publish-year": "1949",
        "author": "George Orwell"
      }
    }
  ]
}

Transcript

JSONAPI is meant to be a standard data format for sending and receiving data between clients and servers. It also happens to be the way in which Ember data 2.0 represents its data internally. And there’s a built-in serializer and adapter for it.

Now here we have the exact specification for JSONAPI 1.0. But it’s very long. It’s about 8000 words, longer than that actually. And that’s just the specification. There’s plenty of stuff on extensions, different recommendations, examples, a list of implementations. So if you get to the end of this episode and you want more, there’s plenty. But in this episode, we’re going to concentrate more on how JSONAPI works with Ember data.

So here in this JSONAPI blob, we’ve got two properties, data and included. data is the main thing that’s being returned, it’s what we ask for specifically, here quote of id 6. It can also be an array. Here’s an array of all the quotes. Included on the other hand is optional, and it’s used for side-loaded data. When I say optional, if you have side-loaded data, you need it, and it is always an array.

So within these, here we have a single JSONAPI object, and notice that this is also in the form of a JSONAPI object. So that’s one of our basic building blocks for building out JSONAPI responses. So the minimal form for these is a type and an id. The type is plural and then the id is a string, even though here it’s a string of a number. It can also have attributes and relationships. Here the quote just has one attribute, and that’s the body, and in this case it’s a string of a quote. The relationships, here it’s related to a book, and then once again you have another JSONAPI object as the book, and here it’s the minimal form of a JSONAPI object. And this book that we’re referring to because we’re side-loading stuff is the one that’s included here. And while we’re here I want to point out here publish-year, it’s two words and it’s not CamelCase like Ember and JavaScript like to do. It’s kebab-case. So keep that in mind if you’re constructing JSONAPI .

So let’s look at a slightly different example from the same data set. And here we’re getting the first book, and we’ll see that the relationships, the data can be an array. And notice here quotes is plural, but here book was singular. So even though the type is always plural, the relationship type can be singular or plural depending on whether there’s one or many.

So those are the basics of the JSONAPI object, with its type, id, attributes, and relationships, and how to construct a basic JSONAPI response. As we go on with this series, we’ll run into lots of methods on the JSONAPI serializer that are meant to account for slight variations on how these are constructed. So if your server isn’t perfectly JSONAPI, we can handle it.

In our time remaining, let’s go over some of the optional things. So you’ll see here in the guides that there’s something called links in addition to type, id, attributes, and relationships. And links are optional if you’re using Ember data. So they’re meant for redirecting you back to the server in a specified way. But Ember data already has really strong conventions [04:38], so the need for links is decreased. However, if you do have links, then Ember data will try to use those in order to get the connected data.

When you’re fetching data, JSONAPI also gives you the optional options of doing sorting, pagination, and filtering. So if you want to do that, they have a specified way. If you’re wanting to do that with Ember data, you’ll have to use the query method. If you’re just doing findAll or findRecord, then it’s difficult to do that. There are also specified ways of doing query parameters and errors, and there’s also specified ways of creating, updating, and deleting resources. And we’ll go over this more when we are looking at serializing the data. But the basic overview is that it’s still using the JSONAPI objects, although when you’re creating a resource, it won’t have an id, and you can do it with basically an inverse like here, or there are other ways to do it with a lot of the information stored like here, with it stored in the url.

So that’s the basics of using JSONAPI with Ember data. As you can see, it’s working within our app. And I look forward to seeing you next time when we start to go into several of the methods that you can use to adapt for things aren’t quite exactly compliant with the JSONAPI spec. I’ll see you then.

Introduction to Ember Data 2.0

Subscribe to our mailing list