Skip to content

Introduce v media type parameter to specify media type version #1245

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

Closed
wants to merge 1 commit into from
Closed

Introduce v media type parameter to specify media type version #1245

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
Introduce v media type parameter for v1.1 
Require that the `v` media type parameter be present to identify 
a specific version of the JSON API media type.

If this parameter is not present, version 1.0 of the spec must be 
assumed.
  • Loading branch information
@dgeb
dgeb committed Dec 8, 2017
commit 11e6f486d83d8ccfcba9ba727d83d059340df737
129 changes: 73 additions & 56 deletions _format/1.1/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,38 +24,55 @@ interpreted as described in RFC 2119

## <a href="#content-negotiation" id="content-negotiation" class="headerlink"></a> Content Negotiation

### <a href="#content-negotiation-version" id="content-negotiation-version" class="headerlink"></a> Version

The base JSON API media type **MUST** be associated with the media type
parameter `v` to specify the version of the media type. This document describes
version 1.1 of the media type. In order for this version of the JSON API
specification to apply, the `v` media type parameter **MUST** be present and
have a value of `1.1`.

If the media type parameter is not specified, version 1.0 of this specification
**MUST** be assumed. This version is described in an earlier version of this
document.

### <a href="#content-negotiation-clients" id="content-negotiation-clients" class="headerlink"></a> Client Responsibilities

Clients **MUST** send all JSON API data in request documents with the header
`Content-Type: application/vnd.api+json` without any media type parameters.
`Content-Type: application/vnd.api+json;v=1.1` without any additional media type
parameters.

Clients that include the JSON API media type in their `Accept` header **MUST**
specify the media type there at least once without any media type parameters.
specify the media type there at least once without any media type parameters
other than `v`.

Clients **MUST** ignore any parameters for the `application/vnd.api+json`
media type received in the `Content-Type` header of response documents.
Clients **MUST** ignore any parameters, other than `v`, for the
`application/vnd.api+json` media type received in the `Content-Type` header of
response documents.

### <a href="#content-negotiation-servers" id="content-negotiation-servers" class="headerlink"></a> Server Responsibilities

Servers **MUST** send all JSON API data in response documents with the header
`Content-Type: application/vnd.api+json` without any media type parameters.
`Content-Type: application/vnd.api+json;v=1.1` without any additional media type
parameters.

Servers **MUST** respond with a `415 Unsupported Media Type` status code if
a request specifies the header `Content-Type: application/vnd.api+json`
with any media type parameters.
with any media type parameters other than `v`.

Servers **MUST** respond with a `406 Not Acceptable` status code if a
request's `Accept` header contains the JSON API media type and all instances
of that media type are modified with media type parameters.
of that media type are modified with media type parameters other than `v`.

> Note: The content negotiation requirements exist to allow future versions
of this specification to use media type parameters for extension negotiation
and versioning.
of this specification to use media type parameters for extension and profile
negotiation.

## <a href="#document-structure" id="document-structure" class="headerlink"></a> Document Structure

This section describes the structure of a JSON API document, which is identified
by the media type [`application/vnd.api+json`](http://www.iana.org/assignments/media-types/application/vnd.api+json).
This section describes the structure of a JSON API v1.1 document, which is identified
by the media type [`application/vnd.api+json`](http://www.iana.org/assignments/media-types/application/vnd.api+json)
together with the media type parameter `v=1.1`.
JSON API documents are defined in JavaScript Object Notation (JSON)
[[RFC7159](http://tools.ietf.org/html/rfc7159)].

Expand Down Expand Up @@ -510,7 +527,7 @@ Each member of a links object is a "link". A link **MUST** be represented as
either:

* a string containing the link's URL.
* <a id="document-links-link-object"></a>an object ("link object") which can
* <a id="document-links-link-object"></a>an object ("link object") which can
contain the following members:
* `href`: a string containing the link's URL.
* `meta`: a meta object containing non-standard meta-information about the
Expand Down Expand Up @@ -703,7 +720,7 @@ For example, a `GET` request to a collection of articles could return:

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1

{
"links": {
Expand All @@ -729,7 +746,7 @@ A similar response representing an empty collection would be:

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1

{
"links": {
Expand All @@ -755,7 +772,7 @@ For example, a `GET` request to an individual article could return:

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1

{
"links": {
Expand Down Expand Up @@ -783,7 +800,7 @@ resource would return:

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1

{
"links": {
Expand Down Expand Up @@ -818,14 +835,14 @@ For example, the following request fetches data about an article's comments:

```http
GET /articles/1/relationships/comments HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

And the following request fetches data about an article's author:

```http
GET /articles/1/relationships/author HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

#### <a href="#fetching-relationships-responses" id="fetching-relationships-responses" class="headerlink"></a> Responses
Expand All @@ -847,7 +864,7 @@ return:

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1

{
"links": {
Expand All @@ -866,7 +883,7 @@ return:

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1

{
"links": {
Expand All @@ -881,7 +898,7 @@ A `GET` request to a URL from a to-many relationship link could return:

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1

{
"links": {
Expand All @@ -900,7 +917,7 @@ return:

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1

{
"links": {
Expand Down Expand Up @@ -964,15 +981,15 @@ For instance, comments could be requested with an article:

```http
GET /articles/1?include=comments HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

In order to request resources related to other resources, a dot-separated path
for each relationship name can be specified:

```http
GET /articles/1?include=comments.author HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

> Note: Because [compound documents][compound document] require full linkage
Expand All @@ -994,14 +1011,14 @@ Multiple related resources can be requested in a comma-separated list:

```http
GET /articles/1?include=author,comments.author HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

Furthermore, related resources can be requested from a relationship endpoint:

```http
GET /articles/1/relationships/comments?include=comments.author HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

In this case, the primary data would be a collection of
Expand All @@ -1027,7 +1044,7 @@ that type in its response.

```http
GET /articles?include=author&fields[articles]=title,body&fields[people]=name HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

> Note: The above example URI shows unencoded `[` and `]` characters simply for
Expand Down Expand Up @@ -1058,7 +1075,7 @@ query parameter. The value for `sort` **MUST** represent sort fields.

```http
GET /people?sort=age HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

An endpoint **MAY** support multiple sort fields by allowing comma-separated
Expand All @@ -1067,15 +1084,15 @@ order specified.

```http
GET /people?sort=age,name HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

The sort order for each sort field **MUST** be ascending unless it is prefixed
with a minus (U+002D HYPHEN-MINUS, "-"), in which case it **MUST** be descending.

```http
GET /articles?sort=-created,title HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

The above example should return the newest articles first. Any articles
Expand Down Expand Up @@ -1174,8 +1191,8 @@ For instance, a new photo might be created with the following request:

```http
POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": {
Expand Down Expand Up @@ -1216,8 +1233,8 @@ For example:

```http
POST /photos HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": {
Expand Down Expand Up @@ -1256,7 +1273,7 @@ member **MUST** match the value of the `Location` header.
```http
HTTP/1.1 201 Created
Location: http://example.com/photos/550e8400-e29b-41d4-a716-446655440000
Content-Type: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1

{
"data": {
Expand Down Expand Up @@ -1339,8 +1356,8 @@ For example:

```http
PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": {
Expand Down Expand Up @@ -1368,8 +1385,8 @@ update only the `title` and `text` attributes of an article:

```http
PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": {
Expand Down Expand Up @@ -1401,8 +1418,8 @@ For instance, the following `PATCH` request will update the `author` relationshi

```http
PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": {
Expand All @@ -1422,8 +1439,8 @@ the `tags` for an article:

```http
PATCH /articles/1 HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": {
Expand Down Expand Up @@ -1547,8 +1564,8 @@ For example, the following request updates the author of an article:

```http
PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": { "type": "people", "id": "12" }
Expand All @@ -1559,8 +1576,8 @@ And the following request clears the author of the same article:

```http
PATCH /articles/1/relationships/author HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": null
Expand Down Expand Up @@ -1588,8 +1605,8 @@ For example, the following request replaces every tag for an article:

```http
PATCH /articles/1/relationships/tags HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": [
Expand All @@ -1603,8 +1620,8 @@ And the following request clears every tag for an article:

```http
PATCH /articles/1/relationships/tags HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": []
Expand Down Expand Up @@ -1632,8 +1649,8 @@ comments for the article with ID `1`:

```http
POST /articles/1/relationships/comments HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": [
Expand All @@ -1658,8 +1675,8 @@ from the list of comments for the article with ID `1`:

```http
DELETE /articles/1/relationships/comments HTTP/1.1
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json;v=1.1
Accept: application/vnd.api+json;v=1.1

{
"data": [
Expand Down Expand Up @@ -1727,7 +1744,7 @@ resource's URL:

```http
DELETE /photos/1 HTTP/1.1
Accept: application/vnd.api+json
Accept: application/vnd.api+json;v=1.1
```

#### <a href="#crud-deleting-responses" id="crud-deleting-responses" class="headerlink"></a> Responses
Expand Down
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