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,

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 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. Designing a custom XML format seems unnecessary, but there's no obvious standard format to use.

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

URL Space

/ --returns list of (mailing list name, URL, public/private flag) tuples.

/list/<list-id>/

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

/list/<list-id>/settings -- dictionary of list settings.

/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).

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

• Initial Considerations

• Initial URL design

• Original Use Cases

• restserver-branch

Comments