Skip to content

Deprecate existing extensions #1026

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 13, 2016
Merged

Deprecate existing extensions #1026

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9c74911
Deprecate the experimental extension system.
ethanresnick Apr 13, 2016
8784926
Tweak config/gemfile
ethanresnick Apr 13, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 2 additions & 9 deletions Gemfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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']
Expand Down
5 changes: 0 additions & 5 deletions _config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
113 changes: 1 addition & 112 deletions extensions/bulk/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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" }
]
}
```
183 changes: 13 additions & 170 deletions extensions/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy