Revision 32 as of 2009-04-01 13:44:45

Clear message

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

h3. user

  • preferences (create, modify)

Changes a user can make to his list-specific settings, but also to all of his subscriptions on the server.

  • identity (create, modify)

Changes a user can make to his list-specific identity, but also to all of his identities on all subscriptions on the server.

  • subscription (create, modify, delete)

Changes a user can make to his list-specific subscription settings e.g. preferred mail-address, but also to all of his subscriptions on the server.

h3. moderator

  • messages (approve, reject, discard, defer)

Handle pending requests.

  • subscriptions (approve, reject, defer)

Handle subscription tasks.

h3. owner

  • lists (create, modify, delete)

Manage list related tasks.

  • subscriptions (create, modify, delete)

Handle subscription tasks.

  • users (create, modify, delete)

Handle user management tasks.

  • statistics (read)

Read server, domain, list, user-related statistics e.g. Top Ten Posters, List Activity Meter

DEV/Original Use Cases

Principles

Initial Considerations
We use JSON. Libraries are available for most relevant programming languages and it's reasonably human-readable.

Also taking the recommendation of Leonard Richardson we will also honor the representation request in the Accept and Accept-Language headers.

URL Space

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

URL
Action
/ TODO: What does it list?
/sys TODO: What does it list?
/sys/version Return Mailman and Python version, read-only
/sys/plugins List all plugins (name, description, author, version)
/sys/plugins/<plugin>
Detailed info on a plugin
/stats/ List of statistics available
/stats/site TODO: What does it list?
Show lists by activity
/stats/domain TODO: What does it list?
Show comparison of lists activity within the same domain
/stats/list TODO: What does it list?
Show list activity (new messages per day, replies to new messages same day)
/stats/users TODO: What does it list?
  • Top Ten Senders
  • Top Ten Contributers
/stats/users/<username> TODO: What does it list?
/users/ TODO: What does it list?
List of all users
/users/<username> TODO: What does it list?
/subscriptions/ TODO: What does it list?
/subscriptions/... TODO: What's beneath?
/addresses/ TODO: What's beneath?
/lists/ returns list of (mailing list name, URL, public/private flag) tuples. POST is used to create a new list and redirect
/lists/<list-id> lists list homepage info
/list/<list-id>/<setting> Arbitrary <settings> that configure a list
/domains/ TODO: What does it list?
List all lists within a domain?
Configure global/default settings of all lists within the domain?
/messages/ A list of all messages? No...
/messages/<message-id> TODO: What does it list?
Header-Info: Sender, Recipient, Date, Subject, Size

OLD

URL
Action
/ ???
/list/ returns list of (mailing list name, URL, public/private flag) tuples.
POST is used to create a new list and redirect
/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.
POST adds one or more subscriptions, providing a mass-subscribe feature.
/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.

  • How should passwords be dealt with?

Should there just be a password='abcdef' setting among all the others, or should the client be expected to SHA1-encode the password or do other stuff with it?

Comments

Cliff Ingham

I'm needing to build a standalone webservice for Mailman that our content manager can access. I'm most comfortable in PHP, so it's probably going to be PHP instead of Python.

But it will be needing to support authentication for usage. I'm planning on it just being a wrapper for the command line tools. If folks are interested, I could contribute our code as it goes. All our work here at the City of Bloomington is GPL. Either way, I'd be very interested in seeing a native RESTful interface come with Mailman