Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Media type negotiation cleanup #673

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
ethanresnick wants to merge 3 commits into from
Closed

Media type negotiation cleanup #673

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9e338b3
Rename Media Type Negotiation to Content Negotiation
ethanresnick May 27, 2015
bc47c04
Content Negotiation: clarify client & server obligations and conseque…
ethanresnick May 27, 2015
a6a051c
Content Negotiation: add non-normative note about serving JSON API as…
ethanresnick May 27, 2015
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
60 changes: 29 additions & 31 deletions format/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,28 +26,40 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
interpreted as described in RFC 2119
[[RFC2119](http://tools.ietf.org/html/rfc2119)].

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

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

Clients **MUST** ignore all parameters for the `application/vnd.api+json`
media type received in the `Content-Type` header of response documents.
If a client violates this requirement, servers **MUST** respond with a
`415 Unsupported Media Type` status code.

@bintoro bintoro May 23, 2015

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm thinking this paragraph could perhaps be deleted.

@ethanresnick ethanresnick May 23, 2015

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought that too for a while. But I decided to leave it because we might, in the future, want to let the server to automatically opt the client in to some parameters (e.g. profile, which just adds extra semantics) and, if we do that, we don't want old clients to blow up.

@bintoro bintoro May 23, 2015

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, obviously clients are not permitted to blow up in the face of unexpected parameters. I just thought that would be... well, obvious. Maybe it's indeed better to leave this intact just in case.

However, right now the paragraph is right between the two requirements to which "either of the requirements above" is intended to refer, so you may want to consider moving it to the very end or explicitly mentioning "request requirements above" or something like that.

@ethanresnick ethanresnick May 23, 2015

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I reordered the paragraphs a bit. Let me know what you think, and thanks always for your close readings!

@bintoro bintoro May 23, 2015

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it reads much better now 👍

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.

If a client violates this requirement, and its `Accept` header doesn't contain
any other media types that the server can produce, the server **MUST** respond
with a `406 Not Acceptable` status code.

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

@bintoro bintoro May 23, 2015

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add "without any media type parameters" here as well.

@ethanresnick ethanresnick May 23, 2015

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, I added this both here and in the first paragraph. I'm not 100% sure it's necessarily, but it certainly can't hurt.

Servers **MUST** return a `406 Not Acceptable` status code if the
`application/vnd.api+json` media type is modified by the `ext` parameter in
the `Accept` header of a request. Otherwise, servers **MUST** return a `415
Unsupported Media Type` status code if the `application/vnd.api+json` media
type is modified by the `ext` parameter in the `Content-Type` header of a
request. Servers **MUST** ignore all other parameters for the
`application/vnd.api+json` media type in `Accept` and `Content-Type`
headers.
Servers **MUST NOT** send responses with the `application/vnd.api+json` media
type if the client has not indicated, using its `Accept` header, that it can
understand this format.

> Note: These requirements may allow future versions of this specification
to support an extension mechanism based upon the `ext` media type parameter.
> Note: If a client's `Accept` header indicates that it accepts standard JSON

@tkellen tkellen May 27, 2015

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should encourage this. I believe that this minor wheel greasing will actually be a disservice to clients. If they are required to provide the media type they accept, I suspect they will be more likely to find out what it is before consuming the data from a json-api service blindly.

@tkellen tkellen May 27, 2015

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For context, I intend to provide a formatter for text/html in Endpoints that will return the response in a browser friendly format (tables, hyperlinks, etc).

but not the JSON API media type, the server may choose serve it a JSON API
document identified as `application/json`. If the server does so, is not
considered to be sending "JSON API data" for the purposes of the requirement
above, but rather simple JSON data, and the client cannot rely on any of the
rules laid out in this specification.

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

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

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

Expand Down Expand Up @@ -592,16 +604,6 @@ The following characters **MUST NOT** be used in member names:
Data, including resources and relationships, can be fetched by sending a
`GET` request to an endpoint.

Clients **MUST** indicate that they can accept the JSON API media type, per
the semantics of the HTTP `Accept` header. If present, this header value **MUST**
also include any media type extensions relevant to the request. Servers **MUST**
return a `406 Not Acceptable` status code if this header specifies an
unsupported media type.

> Note: Servers may support multiple media types at any endpoint. For example,
a server may choose to support `text/html` in order to simplify viewing content
via a web browser.

Responses can be further refined with the optional features described below.

### Fetching Resources <a href="#fetching-resources" id="fetching-resources" class="headerlink"></a>
Expand Down Expand Up @@ -1071,10 +1073,6 @@ strategies.
A server **MAY** allow resources of a given type to be created. It **MAY**
also allow existing resources to be modified or deleted.

Any requests that contain content **MUST** include a `Content-Type` header
whose value is `application/vnd.api+json`. This header value **MUST** also
include media type extensions relevant to the request.

A request **MUST** completely succeed or fail (in a single "transaction"). No
partial updates are allowed.

Expand Down