json-api · wycats · Feb 18, 2015 · Dec 24, 2014 · Jan 7, 2015 · Jan 9, 2015
diff --git a/_config.yml b/_config.yml
@@ -17,12 +17,12 @@ pygments: false
 port: 9876
 
 navigation:
-- title: Overview
-  url: /
 - title: Format
   url: /format/
-- title: Extending
-  url: /extending/
+- title: Extensions
+  url: /extensions/
+- title: Recommendations
+  url: /recommendations/
 - title: Examples
   url: /examples/
 - title: FAQ

diff --git a/extending/index.md b/extending/index.md
diff --git a/extensions/bulk/index.md b/extensions/bulk/index.md
@@ -0,0 +1,105 @@
+---
+layout: page
+title: "Bulk Extension"
+---
+
+## Introduction <a href="#introduction" id="introduction" class="headerlink"></a>
+
+The "Bulk extension" is an [official
+extension](/extensions/#official-extensions) of the JSON API specification.
+It provides support for performing multiple operations in a request,
+including adding and removing multiple resources.
+
+Servers **SHOULD** indicate support for the JSON API media type's Bulk
+extension by including the header `Content-Type: application/vnd.api+json;
+ext=bulk` in every response.
+
+Clients **MAY** request the JSON API media type's Bulk extension by
+specifying the header `Accept: application/vnd.api+json; ext=bulk`. Servers
+that do not support the Bulk extension **MUST** return a `415 Unsupported
+Media Type` status code.
+
+## Bulk Operations <a href="#bulk-operations" id="bulk-operations" class="headerlink"></a>
+
+[As mentioned in the base specification](/format/#crud), a request **MUST**
+completely succeed or fail (in a single "transaction").
+
+Therefore, any request that involves multiple operations **MUST** only
+succeed if all operations are performed successfully. The state of the
+server **MUST NOT** be changed by a request if any individual operation fails.
+
+## Creating Multiple Resources <a href="#creating-multiple-resources" id="creating-multiple-resources" class="headerlink"></a>
+
+Multiple resources can be created by sending a `POST` request to a URL that
+represents a collection of resources. The request **MUST** include an array
+of resource objects as primary data. Each resource object **MUST** contain
+at least a `type` member.
+
+For instance, multiple photos might be created with the following request:
+
+```text
+POST /photos
+Content-Type: application/vnd.api+json; ext=bulk
+Accept: application/vnd.api+json; ext=bulk
+
+{
+  "data": [{
+    "type": "photos",
+    "title": "Ember Hamster",
+    "src": "http://example.com/images/productivity.png"
+  }, {
+    "type": "photos",
+    "title": "Mustaches on a Stick",
+    "src": "http://example.com/images/mustaches.png"
+  }]
+}
+```
+
+
+## Updating Multiple Resources <a href="#updating-multiple-resources" id="updating-multiple-resources" class="headerlink"></a>
+
+Multiple resources can be updated by sending a `PUT` request to a URL that
+represents a collection of resources to which they all belong. The request
+**MUST** include an array of resource objects as primary data. Each resource
+object **MUST** contain at least `type` and `id` members.
+
+For example:
+
+```text
+PUT /articles
+Content-Type: application/vnd.api+json; ext=bulk
+Accept: application/vnd.api+json; ext=bulk
+
+{
+  "data": [{
+    "type": "articles",
+    "id": "1",
+    "title": "To TDD or Not"
+  }, {
+    "type": "articles",
+    "id": "2",
+    "title": "LOL Engineering"
+  }]
+}
+```
+
+## Deleting Multiple Resources <a href="#deleting-multiple-resources" id="deleting-multiple-resources" class="headerlink"></a>
+
+Multiple resources can be deleted by sending a `DELETE` request to a URL that
+represents a collection of resources to which they all belong.
+
+The body of the request **MUST** contain a `data` member whose value is an
+object that contains `type` and `ids`, or an array of objects that each
+contain a `type` and `id`.
+
+For example:
+
+```text
+DELETE /articles
+Content-Type: application/vnd.api+json; ext=bulk
+Accept: application/vnd.api+json; ext=bulk
+
+{
+  "data": { "type": "articles", "ids": ["1", "2"] }
+}
+```
diff --git a/extensions/index.md b/extensions/index.md
@@ -0,0 +1,111 @@
+---
+layout: page
+title: Extensions
+---
+
+JSON API can be extended in several ways:
+
+* The `ext` media type parameter can be used to declare and request support for
+  extensions, [as discussed in the base specification](/format#extending).
+  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](/format/#document-structure-meta).
+
+* A profile can be specified in the top-level `meta` object, as discussed below.
+
+## Official Extensions <a href="#official-extensions" id="official-extensions" class="headerlink"></a>
+
+JSON API currently supports the following official extensions:
+
+* [Bulk extension](/extensions/bulk/) - provides support for performing multiple
+  operations in a request, including adding and removing multiple resources.
+  The Bulk extension is referenced with the media type parameter `ext=bulk`.
+
+* [Patch extension](/extensions/patch/) - provides support for modification of resources
+  with the HTTP PATCH method [[RFC5789](http://tools.ietf.org/html/rfc5789)]
+  and the JSON Patch format [[RFC6902](http://tools.ietf.org/html/rfc6902)].
+  The Patch extension is referenced with the media type parameter `ext=patch`.
+
+## Custom Extensions <a href="#custom-extensions" id="custom-extensions" class="headerlink"></a>
+
+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`
+media type parameter.
+
+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 <a href="#profiles" id="profiles" class="headerlink"></a>
+
+JSON API can be extended with the profile link relation, defined in [RFC
+6906](http://tools.ietf.org/html/rfc6906). See also [this blog post by Mark
+Nottingham](http://www.mnot.net/blog/2012/04/17/profiles).
+
+According to the RFC, profiles are:
+
+```text
+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:
+
+```text
+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:
+
+```text
+GET http://api.example.com/profile HTTP/1.1
+```
+
+```text
+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]`.
+```