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.
--
Nick Coghlan
Red Hat Infrastructure Engineering & Development, Brisbane
Python Applications Team Lead
Beaker Development Lead (
http://beaker-project.org/)
PulpDist Development Lead (
http://pulpdist.readthedocs.org)