jsonapi.md

JSON API

Top Level

The top-level of a JSON API document has the following keys:

• Resource names (posts, comments, people, etc.)
• A meta section

Singular Resources

If the value of a resource name is a JSON object, it represents a single document.

{
  "posts": {
    // an individual post document
  }
}

Resource Collections

If the value of a resource name is a JSON array, it represents a list of documents.

{
  "posts": [{
    // an individual post document
  }, {
    // an individual post document
  }]
}

JSON API Document

A JSON API document is a list of key/value pairs that represent either attributes or relationships.

Attribute or relationship keys SHOULD be camelcased.

Attributes

An attribute's value can be any JSON value:

{
  "posts": {
    title: "Rails is Omakase",
    commentCount: 23
    isDraft: false
  }
}

To-Many Relationships (Using IDs)

To specify a to-many relationship that points to a list of IDs, include it under a "rels" key:

{
  "posts": {
    "id": 1,
    "title": "Rails is Omakase",
    "rels": {
      "comments": [ 1, 3, 12, 17 ]
    }
  }
}

If a to-many relationship is specified as a list of IDs, it SHOULD be possible to fetch a collection of the related documents by making a simple GET request with a URL composed of:

• The URL of the current document
• The part of relationship name converted to underscore format
• A ? followed by the list of IDs, comma-separated

To-Many Relationships (Using URLs)

To specify a to-many relationship that points to a URL, include it under a "rels" key:

{
  "posts": {
    "id": 1,
    "title": "Rails is Omakase",
    "rels": {
      "comments": { "url": "http://example.com/posts/1/comments" }
    }
  }
}

If a to-many relationship is specified as a URL, it MUST be possible to fetch a collection of the related documents by using a simple GET request to the specified URL.

To-Many Relationships (Using URL Templates)

You may also specify a URL template for a relationship as both an array of IDs and a URL template (using {ids} as the parameter):

{
  "posts": {
    "id": 1,
    "title": "Rails is Omakase",
    "rels": {
      "comments": {
        "url": "http://example.com/posts/1/comments/{ids}",
        "ids": [ 1, 2, 4, 12 ]
      }
    }
  }
}

If a to-many relationship is specified both as a URL and an array of IDs, it MUST be possible to fetch a collection of the related documents by:

• Expanding the URL template by substituting the array of IDs into the {ids} variable. This will result in it being replaced with the comma-separated list of IDs.
• Performing a simple GET on the expanded URL

To-One Relationships (Using ID)

To specify a to-one relationship that points to an ID, use a relationship name with an ID suffix whose value is a JSON String or Number.

{
  "posts": {
    "id": 1,
    "title": "Rails is Omakase"
    "rels": {
      "author": 9,
    }
  }
}

If a to-many relationship is specified as an ID, it SHOULD be possible to fetch the related documents by making a simple GET request with a URL composed of:

• The URL of the current document
• A / followed by the part of relationship name before the ID suffix, converted to underscore format
• A / followed by the ID

To-One Relationships (Using URL)

To specify a to-one relationship that points to a URL, use a relationship name with a URL suffix whose value is a URL.

{
  "posts": {
    "id": 1,
    "title": "Rails is Omakase",
    "rels": {
      "author": { "url": "http://example.com/posts/1/author" },
    }
  }
}

If a to-many relationship is specified as a URL, it MUST be possible to fetch the related document by using a simple GET request to the specified URL.

A Resource With Multiple Documents

So far, all resources have contained a single document. You may want to combine multiple documents into a single resource to reduce HTTP queries.

{
  "rels": {
    "posts.author": "http://example.com/people/{posts.id}",
    "posts.comments": "http://example.com/{posts.id}/comments/{posts.comments.ids}"
  },
  "posts": [{
    "id": 1,
    "title": "Rails is Omakase",
    "rels": {
      "comments": [ 1, 2, 5, 17 ]
      "author": 17
    }
  }, {
    "id": 2,
    "title": "The Parley Letter",
    "rels": {
      "comments": [ 3, 4, 6 ]
      "author": 17
    }
  }],
  "http://example.com/people/{id}": [{
    "id": 17,
    "twitterName": "@d2h"
  }]
}

In this case, each relationship specifies a type to link it with

Meta Sections