[Mailman-Developers] Mailman 3 REST API URLs

[Malte S. Stretz]

On Tuesday 20 July 2010 16:50:34 Florian Fuchs wrote:
>[...]
>> For example: At the moment an API request to
> /3.0/lists/listname at 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 at 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 at 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@example.net
echo John Doe | PUT -C user:pass \
  https://lists.example.com/api/lists/foo@lists.example.com/subscribers/user@example.net/name

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