/foo.json or /foo?format=json

[monkeypants]

Currently we use /foo.json throughout the docs, to mean "the resource foo, represented in json format". I don't think that's quite right, everything left of "?" is resource identity, format of the representation of the resource belongs on the right of the "?" like this "/foo?format=json".

We should have a big jelly wrestling session to determine the right way to format encoding specification (or, if both are acceptable, say so). Surely there are recognised authorities that agree with my view, which could be referenced...

[markmuir87]

As far as I can tell, there is no consensus around this issue 'in the wild'. Firebase use the /foo.json approach. MS Sharepoint 2013 use HTTP headers (Content-Type). And I'm sure there are a bunch out there that use /foo?format=json approach. I'm not a fan of the latter approach, as I think things on the right of '?' should only consist of operations on resource representations (e.g. select, stringQuery etc.).

This is kinda a semantic argument, but I think it comes down to how you define 'representations of resources'. So '/foo.json' makes the most sense to me, as it is distinct from the representations '/foo.html' or '/foo.pdf', all of which are representations of the resource 'foo'.

[monkeypants]

if there are multiple patterns that won't surprise users, we should probably list the ones that don't cause problems and say they are all OK, so long as certain principles are maintained (be consistent, document which pattern you are using, anything else?).

limit the proscription to "these patterns are all OK, don't make up your own pattern unless there's a really good reason to do so".

Are there any anti-patterns that we should avoid? Content-Type headers are fine but if it's only on the response, how does a client ask for what they want?

[dke01]

I prefer the Content-Type headers so it keeps the URLs clean. Like what Amazon does with their web services. Put Content-Type: application/json; charset=UTF-8 in the request header. See https://docs.aws.amazon.com/apigateway/api-reference/making-http-requests/ or http://docs.aws.amazon.com/amazonswf/latest/developerguide/UsingJSON-swf.html

[monkeypants]

Content-Type headers are cool for PUT and POST, and responses, but are they de facto-standard (or even sensible) on GET?

[dke01]

Then you could use Accept" headers http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1 that are fine for GET

[monkeypants]

Right, using Headers (rather than encoding in the URL) seems OK then.

@dke01, what's your position, do you feel the Headers-only approach should be allowed, encouraged or mandated?

[monkeypants]

I came across the following post from Roy Fielding, where he advocates the 'foo.json' approach (file extension media-type indication):

https://groups.yahoo.com/neo/groups/rest-discuss/conversations/topics/14844

He cites:

• inconsistencies in how clients handle headers (some are broken) makes Headers unreliable
• query-based media-type indicators are are too long and prone to cache issues

This seems to be the most reasonable argument I have come across. There are certainly examples of all three approaches in the wild.

FWIW my experience with cache-related issues is that they are rare, difficult to reproduce/debug, and only seem to occur when path+query > 256 characters. I think it has something to do with proxy servers (etc) downcasting HTTP/1.1, but never got to the bottom of it.

PROPOSAL

What if our position was:

• use headers correctly, but don't rely on them alone.
• use either file extension or query based media-type indicators in addition to headers
• if you chose query based media-type extensions, then be aware of potential issues caused by long query strings (because they can lead to cache-related issues under some circumstances).