Media type negotiation cleanup #673
Conversation
| @@ -34,20 +34,21 @@ the header `Content-Type: application/vnd.api+json`. | |||
| Clients **MUST** ignore all parameters for the `application/vnd.api+json` | |||
| media type received in the `Content-Type` header of response documents. | |||
|
|
|||
There was a problem hiding this comment.
I'm thinking this paragraph could perhaps be deleted.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Ok, I reordered the paragraphs a bit. Let me know what you think, and thanks always for your close readings!
There was a problem hiding this comment.
I think it reads much better now 👍
|
Some API providers like to supply version information as a media type parameter, so let's be mindful of the fact that such a practice will now be disallowed unless a provision is made for it in these requirements. |
True. Are you saying we should have a non-normative note somewhere pointing this out to people, or make an exception for a version parameter? |
The latter. Not saying we necessarily should, but if we want to accommodate the use case, I think it would be a reasonable provision to reserve something like |
| @@ -592,16 +602,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 | |||
There was a problem hiding this comment.
Rather than saying that "Clients MUST indicate that they can accept the JSON API media type", I'm saying above that "Servers MUST NOT send responses with the application/vnd.api+json media type if the client has not indicated...it can understand this format." This seems to get at what we want—namely, you must ask for JSON API data in order to get it—while giving clients the freedom to ask for the other representations that, as our non-normative note alluded to, can exist at the same endpoint.
0ab8a2d to
323aaa4
Compare
|
@dgeb Ok, I removed the detailed error href, made the note about returning json api as json non-normative, and added |
c3bca68 to
746639e
Compare
|
@ethanresnick thanks! Would you mind squashing these commits down to one, or perhaps a few logical ones. I'd prefer to keep the history sane and free of additions that are removed in the same PR. |
…nces of violating them See rationale in json-api#673. Also consolidates all the rules into the content negotiation section.
746639e to
a6a051c
Compare
|
@dgeb Done! |
|
|
||
| > 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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
|
👍 from me, without commit a6a051c |
…nces of violating them See rationale in #673. Also consolidates all the rules into the content negotiation section.
|
Closing in favor of #703. Thanks for your work here @ethanresnick! |
This does a few things:
ext. Instead, it requires the server to explicitly return an error. We could add all sorts of parameters down the line, and post 1.0–clients that use these parameters may need to know whether they've been honored or not; silent ignoring could be quite unacceptable. By contrast, if we add any parameters down the line that can be simply ignored by old servers, then the post 1.0–client that gets the explicit error can simply retry its request without the parameter. (Of course, none of this effects 1.0 clients, since they're not allowed to include any parameters And, if they do, it's probably a bug, so an explicit error is more helpful for them too.)extas it does to every other media type parameter—namely, it requires the server to send the error mentioned in (1). This is better than using 406/415 here now, which will make it harder, when we add extensions in the future, for clients to distinguish between extensions not being supported at all vs. a particular extension not being supported. Also, there's no guarantee that we'll stick only to theextparameter for required extension negotiation. (My proposal in Extensions Overhaul #650, for example, will, when I finish the last section, have anextand arequired-profileparameter.)Accept: application/vnd.api+json;ext=bulk, application/vnd.api+json, and that the header is only problematic if every JSON-API option it lists contains parameters. If only some of the options contain parameters (as in the prior example), then the requests should succeed—and, in fact, future clients may want to format theirAcceptheader like this to work with older servers.