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

On Jul 20, 2010, at 04:50 PM, 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).

I don't think these need to be mutually exclusive, but of course it's a matter of deciding which approach is more useful to implement first. I think the former will be easier to implement from the server side.

Both will accomplish what you want and will have different performance characteristics. For example, GET on /3.0/lists/listname@example.com can return the entire representation of the mailing list object. POSTs to this would *replace* the state of the object with the new state, but PATCH (which is a non-standard HTTP verb though supported in e.g. httplib2 IIUC) will allow you to modify a small subset of the list's attributes. This can be much more efficient if you're patching a bunch of attributes at the same time because you'll only need to make one request.

I think it comes down to what wui interactions you expect to implement. If you think it'll be more common to change one attribute at a time, then perhaps we should implement lists/settings/foo first, but if you think it'll be more common to change a number of settings in a batch, then implementing PATCH on the list object first would be better. (Aside: I'm not actually sure how best to implement lists/settings/foo ;)

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

I suppose we could implement categories but I see these as an artificial organization in Mailman 3. Mailman 2 had them as an artifact of the implementation, but I never really liked it.

Cheers, -Barry