Skip to content

Latest commit

 

History

History
113 lines (88 loc) · 3.95 KB

index.md

File metadata and controls

113 lines (88 loc) · 3.95 KB
layout title
page
Extensions

JSON API can be extended in several ways:

  • The supported-ext and ext media type parameters can be used to negotiate support for extensions, as discussed in the base specification. Official and custom extensions to the specification are discussed below.

  • Meta information can be included in several places in a document, as discussed in the base specification.

  • A profile can be specified in the top-level meta object, as discussed below.

Official Extensions

JSON API currently supports the following official extensions:

  • Bulk extension - provides support for performing multiple operations in a request, including adding and removing multiple resources. The Bulk extension is referenced with the extension name bulk.

  • JSON Patch extension - provides support for modification of resources with the HTTP PATCH method [RFC5789] and the JSON Patch format [RFC6902]. The JSON Patch extension is referenced with the extension name jsonpatch.

Custom Extensions

The JSON API media type can be extended for your organization by writing your own custom extension. This extension should also be specified using the ext and supported-ext media type parameters.

It is strongly recommended that custom extensions be prefixed with a unique identifier for your organization to avoid namespace collision. For example, my-org/embedded-resources.

Profiles

JSON API can be extended with the profile link relation, defined in RFC 6906. See also this blog post by Mark Nottingham.

According to the RFC, profiles are:

defined not to alter the semantics of the resource representation itself, but
to allow clients to learn about additional semantics (constraints, conventions,
extensions) that are associated with the resource representation, in addition
to those defined by the media type and possibly other mechanisms.

A profile link SHOULD be specified in the top-level meta object, keyed by profile.

For example, let's say that you want your API to support a offset / limit based pagination scheme that you'd like to describe to your users. You would make some sort of profile page on your site, such as http://api.example.com/profile, and then include it in the meta key of your responses:

GET http://api.example.com/posts

{
  "meta": {
    "profile": "http://api.example.com/profile",
    "page": {
      "offset": 1,
      "limit": 10,
      "total": 35
    }
  },
  "links": {
    "self": "http://api.example.com/posts",
    "next": "http://api.example.com/posts?page[offset]=11",
    "last": "http://api.example.com/posts?page[offset]=31"
  },
  "data": [
    // First 10 posts
  ]
}

That document will de-reference to explain your link relations:

GET http://api.example.com/profile HTTP/1.1
HTTP/1.1 200 OK
Content-Type: text/plain

The Example.com API Profile
===========================

The Example.com API uses simple offset and limit-based pagination. Paginated
resources will include the standard JSON API `next`, `prev`, `first`, and
`last` pagination links in the top-level `links` object when they are not
`null`.

In addition, a `page` member will be added to the top-level `meta` object
that includes the following members: `offset`, `limit`, and `total`. The
`total` member represents the total count of resources in the paginated
collection. You can use the `offset` and `limit` members to construct your
own custom pagination links with the query parameters `page[offset]` and
`page[limit]`.