On Tuesday 20 July 2010 16:50:34 Florian Fuchs wrote:
For example: At the moment an API request to /3.0/lists/listname@example.org exposes only some basic list information. Would it be a good idea to let this URL expose more list
[...] details (i.e. all list settings) or would it be better to have a different URL for that? (Something like /3.0/lists/listname@example.com/settings).
Why a different URL for the settings? Obviously the first option (one URL for all list details) would be simpler and, as a developer, you would have all information at hand with only one call. Wether you use that info to build a detailed settings page or just a small list info page wouldn't matter.
On the other hand there are quite a lot of DB fields for every list and that means quite a bit of traffic every time you access them through the API. That's why it could make sense to use different URLs.
So if we went for the latter option: Why not go even further and access the settings field by field? Or in smaller groups, i.e.: /3.0/lists/listname@example.com/settings/archiving
My 2 cents:
I think the one-file-per-option interface is the optimal REST interface because you don't have to cope with some weird format like JSON or XML or whatever. Just PUT your value there and GET it later as text/plain. Just like /sys or Plan9 or mlmmj's config works :)
With Perl's lwp-request installed all I'd need to do to read or change a setting is
GET -C user:pass
https://lists.example.com/api/lists/foo@lists.example.com/real_name
echo "foo" | PUT -C user:pass
https://lists.example.com/api/lists/foo@lists.example.com/real_name
And to add a user maybe
echo | PUT -C user:pass
https://lists.example.com/api/lists/foo@lists.example.com/subscribers/user@e...
echo John Doe | PUT -C user:pass
https://lists.example.com/api/lists/foo@lists.example.com/subscribers/user@e...
And to list all users
GET -C user:pass
https://lists.example.com/api/lists/foo@lists.example.com/subscribers
Quite elegant I think :)
Of course the API could also allow posting and retrieving JSON (or...) based on Content-Type and Accept-Content-Type.
Cheers, Malte