Octect-stream representation of a resource

[Nicolas Faugout]

We are implementing de REST API with resources names "files".

/api/files.json returns the list of files such as user pictures, blog posts attachments, etc..

/api/files/123.json returns file number 123 in JSON format.

A file contains fields such as "name", "id", "author", "lastmodified", etc..

How should I implement the fact that a file could be downloaded ?

I have several options :

1. the octect-stream representation of the file resource can be considered similar to the JSON and XML ones, so I can make /api/files/123.data to get the stream of the file

2. all of my resources have a "url" attribute that points to their API URL, but I could make an exception for the "files", for whom the url coud refer to the downloadable version of the file, like so : { "file": { "id": 123, "url": "/getFile.ashx?id=123" } } but I don't like this approach

3. Any other idea is welcomed !

Thanks a lot.

[chris...@gmail.com]

On Tue, 13 Nov 2012, Nicolas Faugout wrote:

> 1. the octect-stream representation of the file resource can be considered
> similar to the JSON and XML ones, so I can make /api/files/123.data to get
> the stream of the file

Something like this.

Would be best if your API (and browsers, dammit!) supported effective
use of Accept headers so that /api/files/123 could be the uri for
several different representations. The ability to use extensions is a
nice addition for friendly human browsing of representations, but
should be an addition, not a requirement.

--
Chris Dent http://burningchrome.com/
[...]

[Nicolas Faugout]

Thanks for the quick answer.

I had thought of the Accept HTTP Header as well, so I will stick with that.

Do you think that the default representation could be contextual to the type of resource ?

For instance, /api/users/123 returns by default the JSON representation

whereas /api/files/123 returns the octect-stream one ?

This way, within a browser, one could be able to :

- download the file with /api/files/123

- see the file info with /api/files/123.json

- see user info with /api/users/123 or /api/users/123.json

Thanks in advance.

[chris...@gmail.com]

On Tue, 13 Nov 2012, Nicolas Faugout wrote:

> Do you think that the default representation could be contextual to the
> type of resource ?

I personally think so, yes, but I'm not sure that's a consensus among
all the participants in this group.

It can lead to a bit of confusion as people tend to expect a measure
of consistency.

<troll aspect="lighthearted">
I'm sure the HATEOAS fans will say that effective use of hypermedia
alleviates the confusion by controlling the expectations. While I
think this is a fine idea, it's less true in practice when the
audience is a) human b) boundless.
</troll>

[Nicolas Faugout]

Thank you for your advice.

Have a nice day.