JSON-API — The Convention

JSON-API is a strict spec for resource-style JSON over HTTP. Ember Data speaks it natively.

4 min read Level 2/5 #ember#ember-data#json-api

What you'll learn

Recognize a JSON-API response (data, included, relationships)
Know when to use the RESTSerializer instead
Pair with backends like jsonapi-rb or rails-json-api

JSON-API is a media type — a specification for how resource-oriented APIs should look in JSON. Ember Data was co-designed with it, so the defaults are zero-config for a JSON-API server.

Anatomy

{
  "data": {
    "type": "posts",
    "id": "1",
    "attributes": { "title": "Hello" },
    "relationships": {
      "author": { "data": { "type": "users", "id": "7" } }
    }
  },
  "included": [
    {
      "type": "users",
      "id": "7",
      "attributes": { "name": "Ada" }
    }
  ]
}

Key parts:

data — the primary resource or array of resources
attributes — the model’s own fields
relationships — links to other resources
included — side-loaded resources referenced above

Why It Helps

Because the shape is fixed, the store can wire up identity, dedupe, and relationships with no per-endpoint code. A single fetch can pull a post and its author in one round trip via ?include=author.

Errors

JSON-API standardizes error responses too:

{
  "errors": [
    {
      "status": "422",
      "source": { "pointer": "/data/attributes/title" },
      "detail": "Title can't be blank"
    }
  ]
}

Ember Data maps these to per-attribute errors on the record, so forms can display them without extra code.

When To Switch Serializers

If your backend isn’t JSON-API and reshaping it server-side isn’t viable, use RESTSerializer for sidedish-style payloads or write a custom serializer. The store doesn’t care which serializer you use — it always works with normalized records internally.

Server Libraries

Server-side helpers that emit clean JSON-API include jsonapi-rb (Ruby), rails-jsonapi, jsonapi-serializer (Node), and many others. Match the server library to your stack and JSONAPIAdapter will mostly Just Work.

Defining a Service →