Permalink
Browse files

Deprecate existing extensions (#1026)

* Deprecate the experimental extension system.

* Tweak config/gemfile

- the safe: false declaration isn’t needed now that we have
jekyll-redirect-from on the whitelist.

- Jekyll auto regeneration was causing the gem versions to be printed
constantly, so we now disable that printing in the Gemfile.
  • Loading branch information...
1 parent 507fec4 commit 71723cfbf992581db123e28cfdf220312672777f @ethanresnick ethanresnick committed Apr 13, 2016
Showing with 17 additions and 616 deletions.
  1. +2 −9 Gemfile
  2. +0 −5 _config.yml
  3. +1 −112 extensions/bulk/index.md
  4. +13 −170 extensions/index.md
  5. +1 −320 extensions/jsonpatch/index.md
View
@@ -5,16 +5,9 @@ require 'json'
require 'open-uri'
versions =
begin
- versions = JSON.parse(open('https://pages.github.com/versions.json').read)
- unless $skip_print_versions == true
- require 'pp'
- STDERR.puts 'Gem versions are:'
- pp versions
- $skip_print_versions = true
- end
- versions
+ JSON.parse(open('https://pages.github.com/versions.json').read)
rescue SocketError
- { 'github-pages' => 52 }
+ { 'github-pages' => 67 }
end
gem 'github-pages', versions['github-pages']
View
@@ -19,11 +19,6 @@ incremental: false
highlighter: rouge
gist:
noscript: false
-# `safe `must be set false for jekyll-redirect-from
-# to run in development. (Github Pages will override
-# `safe` to be true on deploy, but it makes an
-# exception for jekyll-redirect from.)
-safe: false
# customize github pages
quiet: false
kramdown:
@@ -1,116 +1,5 @@
---
layout: page
title: "Bulk Extension"
+redirect_to: /extensions/#prior-extensions
---
-
-## <a href="#status" id="status" class="headerlink"></a> Status
-
-**Extensions are an experimental feature** and should be considered a work
-in progress. There is no official support for extensions in the base JSON
-API specification.
-
-## <a href="#introduction" id="introduction" class="headerlink"></a> Introduction
-
-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 and clients **MUST** negotiate support for and use of the Bulk extension
-[as described in the base specification](/format/#extending) using `bulk` as the
-name of the extension.
-
-## <a href="#bulk-operations" id="bulk-operations" class="headerlink"></a> Bulk Operations
-
-[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.
-
-## <a href="#creating-multiple-resources" id="creating-multiple-resources" class="headerlink"></a> Creating Multiple Resources
-
-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:
-
-```http
-POST /photos HTTP/1.1
-Content-Type: application/vnd.api+json; ext=bulk
-Accept: application/vnd.api+json; ext=bulk
-
-{
- "data": [{
- "type": "photos",
- "attributes": {
- "title": "Ember Hamster",
- "src": "http://example.com/images/productivity.png"
- }
- }, {
- "type": "photos",
- "attributes": {
- "title": "Mustaches on a Stick",
- "src": "http://example.com/images/mustaches.png"
- }
- }]
-}
-```
-
-
-## <a href="#updating-multiple-resources" id="updating-multiple-resources" class="headerlink"></a> Updating Multiple Resources
-
-Multiple resources can be updated by sending a `PATCH` 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:
-
-```http
-PATCH /articles HTTP/1.1
-Content-Type: application/vnd.api+json; ext=bulk
-Accept: application/vnd.api+json; ext=bulk
-
-{
- "data": [{
- "type": "articles",
- "id": "1",
- "attributes": {
- "title": "To TDD or Not"
- }
- }, {
- "type": "articles",
- "id": "2",
- "attributes": {
- "title": "LOL Engineering"
- }
- }]
-}
-```
-
-## <a href="#deleting-multiple-resources" id="deleting-multiple-resources" class="headerlink"></a> Deleting Multiple Resources
-
-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
-an array of resource identifier objects.
-
-For example:
-
-```http
-DELETE /articles HTTP/1.1
-Content-Type: application/vnd.api+json; ext=bulk
-Accept: application/vnd.api+json; ext=bulk
-
-{
- "data": [
- { "type": "articles", "id": "1" },
- { "type": "articles", "id": "2" }
- ]
-}
-```
View
@@ -4,177 +4,20 @@ title: Extensions
show_sidebar: true
---
-## Status
+## <a href="#status" id="status" class="headerlink"></a> Status
-**Extensions are an experimental feature** and should be considered a work
-in progress. There is no official support for extensions in the base JSON
-API specification.
+**An extension system is currently under development,** and you can view the
+latest work [here](https://github.com/json-api/json-api/tree/profile-extensions).
+There is no official support for extensions in the base JSON API specification.
-## <a href="#extending-json-api" id="extending-json-api" class="headerlink"></a> Extending JSON API
+## <a href="#prior-extensions" id="deprecated-extensions" class="headerlink"></a> Prior Extensions
-JSON API can be extended in several ways:
+JSON API previously offered experimental support for a different extension
+negotiation system than the one now being discussed, and it provided a number of
+extensions for use with that old negotiation system. However, this system was
+always experimental and has now been deprecated.
-* [Official](#official-extensions) and [custom](#custom-extensions) extensions
- are in development. The `supported-ext` and `ext` media type parameters can
- be used to [negotiate support for extensions](#extension-negotiation).
-
-* 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.
-
-## <a href="#extension-negotiation" id="extension-negotiation" class="headerlink"></a> Extension Negotiation
-
-The JSON API specification **MAY** be extended to support additional
-capabilities.
-
-An extension **MAY** make changes to and deviate from the requirements of the
-base specification apart from this section, which remains binding.
-
-Servers that support one or more extensions to JSON API **MUST** return
-those extensions in every response in the `supported-ext` media type
-parameter of the `Content-Type` header. The value of the `supported-ext`
-parameter **MUST** be a comma-separated (U+002C COMMA, ",") list of
-extension names.
-
-For example: a response that includes the header `Content-Type:
-application/vnd.api+json; supported-ext="bulk,jsonpatch"` indicates that the
-server supports both the "bulk" and "jsonpatch" extensions.
-
-If an extension is used to form a particular request or response document,
-then it **MUST** be specified by including its name in the `ext` media type
-parameter with the `Content-Type` header. The value of the `ext` media type
-parameter **MUST** be formatted as a comma-separated (U+002C COMMA, ",")
-list of extension names and **MUST** be limited to a subset of the
-extensions supported by the server, which are listed in `supported-ext`
-of every response.
-
-For example: a response that includes the header `Content-Type:
-application/vnd.api+json; ext="ext1,ext2"; supported-ext="ext1,ext2,ext3"`
-indicates that the response document is formatted according to the
-extensions "ext1" and "ext2". Another example: a request that includes
-the header `Content-Type: application/vnd.api+json; ext="ext1,ext2"`
-indicates that the request document is formatted according to the
-extensions "ext1" and "ext2".
-
-Clients **MAY** request a particular media type extension by including its
-name in the `ext` media type parameter with the `Accept` header. Servers
-that do not support a requested extension or combination of extensions
-**MUST** return a `406 Not Acceptable` status code.
-
-If the media type in the `Accept` header is supported by a server but the
-media type in the `Content-Type` header is unsupported, the server
-**MUST** return a `415 Unsupported Media Type` status code.
-
-Servers **MUST NOT** provide extended functionality that is incompatible
-with the base specification to clients that do not request the extension in
-the `ext` parameter of the `Content-Type` or the `Accept` header.
-
-> Note: Since extensions can contradict one another or have interactions
-that can be resolved in many equally plausible ways, it is the
-responsibility of the server to decide which extensions are compatible, and
-it is the responsibility of the designer of each implementation of this
-specification to describe extension interoperability rules which are
-applicable to that implementation.
-
-When the value of the `ext` or `supported-ext` media type parameter contains
-more than one extension name, the value **MUST** be surrounded with quotation
-marks (U+0022 QUOTATION MARK, """), in accordance with the HTTP specification.
-
-## <a href="#official-extensions" id="official-extensions" class="headerlink"></a> Official Extensions
-
-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 extension name `bulk`.
-
-* [JSON Patch extension](/extensions/jsonpatch/) - 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 JSON Patch extension is
- referenced with the extension name `jsonpatch`.
-
-## <a href="#custom-extensions" id="custom-extensions" class="headerlink"></a> 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`.
-
-## <a href="#profiles" id="profiles" class="headerlink"></a> Profiles
-
-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:
-
-```http
-GET http://api.example.com/posts HTTP/1.1
-
-{
- "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:
-
-```http
-GET http://api.example.com/profile HTTP/1.1
-```
-
-```http
-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]`.
-```
+New APIs should not use the old system or any extensions designed for it. APIs
+that already use these old extensions should direct clients to an
+[earlier version of this page](https://github.com/json-api/json-api/blob/9c7a03dbc37f80f6ca81b16d444c960e96dd7a57/extensions/index.md)
+as documentation.
Oops, something went wrong.

0 comments on commit 71723cf

Please sign in to comment.