Not following the HTTP speciication for content negotiation

[pkarouzos]

Hi

I would like to suggest the api guide follow the HTTP specification in regards to content negotiation. This would simplifying the approach for a consumer of an API as they will only have to set the HTTP ACCEPT header to the format they wish. Not have to worry as well with the URI.

For more information http://www.w3.org/Protocols/rfc2616/rfc2616-sec12.html

Peter

[monkeypants]

this came up before, see #25.

The issue is that HTTP ACCEPT depends on consistency in client implementation, which is not perfectly reliable. So it's a fine option, but not quite sufficient.

[markmuir87]

I do agree though that the docs should clarify only one approach should be used (either HTTP headers or 'filetype' extensions, but not both at the same time as it's redundant and increases complexity / probability of error).

I argued for the 'filetype' approach because it made more sense to me conceptually if we're talking about representations of resources. It also reinforces RESTful thinking IMHO (as I said in #25, it makes it more explicit that 'foo.json', 'foo.pdf' and 'foo.html' are simply different representations of the resource 'foo').

On a more practical level, it generally saves devs a line or two of code (though I agree it makes the URL seem 'uglier', somehow).

In the grand scheme of things, all fairly trivial issues; I'm comfortable with either approach. If you do come down on one side or the other, the deciding factor should be whatever devs prefer. @pkarouzos , what's your preference from a practical perspective?

Any other devs welcome to chime in too...

[pkarouzos]

Hi @markmuir87 @monkeypants

I recently developed guidelines for the developing Rest api. With no wrong way and with so many views on the topic I found myself jumping between the two approaches. I settled on the use of the headers for the following reasons:

1. The purpose of the URI is to identify a resource. The location of the resource does not change regardless of how it is represented.
2. Accept headers is the semantic of the http specification for a client to specify how the resource should be represented. Consumers of Ali would expect consistent use all of the specification's semantics
3. Consistent use of headers when managing other aspects of content. For example compression, paging etc. one scenario is when a client wishes to retrieve a file not knowing the type of file would have to check the headers to find out
4. Leveraging the accept header to also support versioning resources definitions within a version of the api

From a dev perspective consistency in the use of a standard is important. The use of headers is intrinsic with http and devs are aware of them.

[markmuir87]

Thanks @pkarouzos! Point no. 1 had never occurred to me (URI/L are universal identifiers/locators of resources, rather than representations). And I think it's a fair assumption, which is made elsewhere in the guide, that adherence to standards/idioms is more likely to cause 'least surprise' (in absence of good reason to think otherwise).

Over to you DTO folks...

[adonm]

Heh as a dev we almost always publish using both (e.g. /api/dataset - use headers, /api/dataset.json - force json ignore headers, /api/dataset.csv - force csv ignore headers), as to get user traction being able to send around plain links is quite convenient.