Sketch of a REST interface to Mailman

This interface isn't intended to be exposed to the Internet at large, so there's no mention of access control. It would be used as a back-end, on top of which the existing Mailman interface, or a fancy GUI application, or administrative scripts, could be built.

Resource Types

• Lists
• Users
• Subscriptions (which tie together a single user and a single list).
• Messages.

Use Cases

• Getting Mailman version.
• Idea: Getting version of REST interface.
• Creating a list
• Deleting a list
• Changing list settings (e.g. setting/clearing the moderation flag)
• Retrieving list statistics (# of posts, bounces, etc.)
• Adding a user to a list (using default options)
• Checking if password provided matches that of user(Authentication)
• Change/Reset password
• Checking if a user is subscribed to a particular list
• Setting user options (digest, topics, etc.), both for a single list and across all subscribed-to lists.
• Unsubscribing a user.
• Retrieving user statistics (# of posts, bounce status, etc.)

Principles

One question is what to use for the representation of each resource? That is, when you access a user's settings by retrieving some URL, what format are the results in? We could use:

• HTML
• An existing XML format for representing data structures, such as XML-RPC's serialization.
• A custom-designed XML format.

• JSON

I suggest using JSON. Libraries are available for most relevant programming languages and it's reasonably human-readable. There's no obvious standard format to use; designing a custom XML format also seems unnecessary.

In the URL paths, do we want to use human-readable list names and e-mail addresses, or identifiers? For example, do we want /list/mailman-developers/, or /list/123456/? The human-readable names make it convenient to poke around on the REST interface, but also require us to worry about quoting -- can you have a list named 'foo/bar'? -- and people may assemble URLs instead of looking up the correct one.

URL Space

Unless otherwise specified, all these URLs return a data structure encoded as JSON.

/ -- Returns Mailman version.

/list/ --returns list of (mailing list name, URL, public/private flag) tuples. POST is used to create a new list and redirect to the new list's URL.

/list/<list-id>/ -- XXX what's useful to return here? links to settings and subscriptions, maybe?

/list/<list-id>/subscriptions -- list of (e-mail address, subscription URL) tuples.

/list/<list-id>/settings -- dictionary of list settings. PUT updates the settings.

/list/<list-id>/statistics -- retrieves statistical info.

/user/ -- POST creates a new user account and redirects to the new user's URL.

/user/?email=bob@example.com -- redirects to the user's URL, or returns a 404.

/user/<user-id>/subscriptions -- list of (mailing-list URL, subscription URL) tuples.

/user/<user-id>/settings -- dictionary of site-wide user settings (e.g. password).

/user/<user-id>/statistics -- retrieves statistical info.

/subscription/<sub-id>/settings -- dictionary of settings for this list/user. PUT updates the settings.

Unresolved Questions

What to do with bounce status/other logging information? By this I mean the info that the Mailman core will generate that the other side may need to know.

• Initial Considerations

• Initial URL design

• Original Use Cases

• restserver-branch

Comments