On 02/22/2013 01:17 PM, Dan Callaghan wrote:
Excerpts from Nick Coghlan's message of 2013-02-22 13:12:49 +1000:
On 02/22/2013 12:54 PM, Dan Callaghan wrote:
On that note, what are people's preferred ways of returning a listing of resources (e.g. GET /recipe/1234/logs/)? HTML, Atom, JSON array of hrefs, ...?
For PulpDist, I used djangorestframework's content negotiation to publish human readable HTML, XML and JSON. I don't think we need to go that far - basic structured data as JSON files should suffice (and is the REST tradition).
While I don't agree with all the details, my general philosophical guide for RESTy APIs is this article written by one of the RHEV developers: https://restful-api-design.readthedocs.org/en/latest/
This advocates (or seems to advocate) inventing your own un-namespaced XML format for every collection type, which I think is a terrible idea, especially for what I am talking about here which is just returning a set of links to resources in a collection. If you like XML then at least a standard format like Atom is a nicer choice.
Not really. The important is referencing other collections as something like:
"examples": { "_type": "link", "rel": "collection/examples", "url": "https://hostname/api/examples/" },
And individual resources as something like:
"example": { "_type": "link", "rel": "resource/example", "url": "https://hostname/api/examples/specific-example/" }
You *could* just use the bare URLs instead of moving them inside a namespace like that, but it gives you a lot more freedom to create self-describing data if you don't.
Cheers, Nick.