|
Size: 2790
Comment:
|
Size: 3411
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #pragma page-filename DEV/versions/3276804 | #pragma page-filename DEV/versions/3276825 |
| Line 40: | Line 40: |
| / --returns list of (mailing list name, URL, public/private flag) tuples. | Unless otherwise specified, all these URLs return a data structure encoded as JSON. |
| Line 42: | Line 42: |
| /list/<list-id>/ | / -- 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? |
| Line 46: | Line 51: |
| /list/<list-id>/settings -- dictionary of list settings. | /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. |
| Line 52: | Line 63: |
| /subscription/<sub-id>/settings -- dictionary of settings for this list/user. | /user/<user-id>/statistics -- retrieves statistical info. /subscription/<sub-id>/settings -- dictionary of settings for this list/user. PUT updates the settings. |
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.
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
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.
Comments
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