👍

Thanks for working on these refinements, @dgeb! I'm excited to get this text in too!

👍 On dividing client and server responsibilities, and on some of your rewordings, which made things far less awkward.

👎 On the sentence "Servers MUST respond with a 406 Not Acceptable status code if a request's Accept header doesn't contain any media types that the server can produce." Again, this is us being more prescriptive than HTTP itself, and feels like stepping out of bounds to me.

👎 On removing the non-normative note about serving JSON API as JSON. I added that because a good server should support this, to make it easier for developers to make requests using generic clients (like curl) without having to go to the (totally unnecessary) trouble of setting a custom Accept header. Responding with JSON as a fallback also just generally makes the API more robust.

Of course, you guys have the final call on all this, but that's my .02

Okay, the curl example has convinced me. I think you're right RE: fallbacks @ethanresnick.

@tkellen Cool! :)

Credit where it's due, though: the idea for the note originally goes back to #518.

If we remove this statement: "Servers MUST respond with a 406 Not Acceptable status code if a request's Accept header doesn't contain any media types that the server can produce."

Then we remove the ability for clients / servers to negotiate based on media type parameters in the future.

This is why I specifically called out the ext parameter in the current section on media type negotiation: http://jsonapi.org/format/#media-type-negotiation

This is awkwardly worded, but provides the allowance we need while (I think) respecting @ethanresnick's concerns about overstepping ourbounds:

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

@dgeb Your reworded clause works for me!

Also, sorry, I should've been clearer originally. I was imagining that, if we removed the sentence, extension negotiation would still work because the client would check the Content-Type of the response to know if the contract has been established successfully. If it got JSON-API content back (eventually, with the extension parameters), things worked; if it got another content type, or a 406, then negotiation has failed.

The theoretical advantage of this would have been that it preserves the flexibility that HTTP allows for responding to a request like:

GET /articles
Accept: text/plain

With:

200 OK
Content-Type: application/json
{
   "data": { //... }
}

Rather than a 406.

Also, my thinking was that clients would have to inspect Content-Type in some cases anyway (and not just rely on status codes) to determine the result of negotiation—as when they say they'll support multiple (combinations of) extensions and they need to know which (combination) was chosen—so it wouldn't be too painful to make them always check that field.

That said, if we can give status code indicators, I think we should, and your new clause seems to let us do that while keeping all of HTTP's allowed wiggle room

@ethanresnick thanks for confirming! I've pushed the reworded clause.

Let's try to get something non-normative in tomorrow that will scratch your itch regarding working with generic clients.

Thanks for re-working this @dgeb. I'm 👍 to merge with that minor change.

Thanks for the careful review @ethanresnick and @tkellen!

@dgeb Absolutely!

Btw, as far as adding the non-normative note about serving application/json goes: let me know you want me to take another stab at that and, if so, whether there's anything in particular that should change from my prior version beyond general concision. Otherwise, if it's easier for you to just write something up yourself, that's fine too.

@ethanresnick Thanks - I'll definitely review your non-normative note again now that the normative changes have been merged.