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
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.
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.
Le mardi 13 novembre 2012 11:57:30 UTC+1, Chris Dent a écrit :
> > 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.
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>
> > 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>
