|
Size: 4163
Comment:
|
Size: 5559
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #pragma page-filename DEV/versions/3604489 | #pragma page-filename DEV/versions/7962684 |
| Line 3: | Line 3: |
| 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, |
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, |
| Line 13: | Line 13: |
| === 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) * subscriptions (approve, reject, defer) === h3. owner === * lists (create, modify, delete) * subscriptions (create, modify, delete) * users (create, modify, delete) * statistics (read) === Original Use Case Proposal === This list contains the original use cases for the user <-> REST client interaction. Use cases that have been merged to the upper section have been marked strikethrough: <<BR>> |
|
| Line 15: | Line 36: |
| * 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) |
* --(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))-- |
| Line 21: | Line 42: |
| * Change/Reset passwords for lists and for users | * --(Change/Reset passwords for lists and for users)-- |
| Line 23: | Line 44: |
| * Setting user options (digest, topics, etc.), both for a single list and across all subscribed-to lists. * Unsubscribing a user. * Mass operations on users (subscribing/unsubscribing a list of e-mails) * Retrieving user statistics (# of posts, bounce status, etc.) |
* --(Setting user options (digest, topics, etc.), both for a single list and across all subscribed-to lists.)-- * --(Unsubscribing a user.)-- * --(Mass operations on users (subscribing/unsubscribing a list of e-mails))-- * --(Retrieving user statistics (# of posts, bounce status, etc.))-- |
| Line 29: | Line 50: |
| One question is what to use for the representation of each resource? That is, when you access a user's settings by retrieving | One question is what to use for the representation of each resource? That is, when you access a user's settings by retrieving |
| Line 32: | Line 53: |
| * HTML | * HTML |
| Line 36: | Line 57: |
| 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. |
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. We decided at pycon08 that we should provide HTML and JSON differentiated by extensions .json and .html and for resources that make sense internationalized we could even do jp.html and so on. Also taking the recommendation of Leonard Richardson we will also honor the representation request in the {{{Accept}}} and {{{Accept-Language}}} headers. |
| Line 41: | Line 62: |
| 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. | 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. |
| Line 46: | Line 67: |
| / -- Returns Mailman version. | / - Returns Mailman version. |
| Line 48: | Line 69: |
| /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/ --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. |
| Line 51: | Line 72: |
| /list/<list-id>/ -- XXX what's useful to return here? links to settings and subscriptions, maybe? | /list/<list-id>/ - XXX what's useful to return here? links to settings and subscriptions, maybe? |
| Line 53: | Line 74: |
| /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>/subscriptions - list of (e-mail address, subscription URL) tuples. POST adds one or more subscriptions, providing a mass-subscribe feature. |
| Line 55: | Line 76: |
| /list/<list-id>/settings -- dictionary of list settings. PUT updates the settings. | /list/<list-id>/settings - dictionary of list settings. PUT updates the settings. |
| Line 57: | Line 78: |
| /list/<list-id>/statistics -- retrieves statistical info. | /list/<list-id>/statistics - retrieves statistical info. |
| Line 59: | Line 80: |
| /user/ -- POST creates a new user account and redirects to the new user's URL. | /user/ - POST creates a new user account and redirects to the new user's URL. |
| Line 61: | Line 82: |
| /user/?email=bob@example.com -- redirects to the user's URL, or returns a 404. | /user/?email=bob@example.com - redirects to the user's URL, or returns a 404. |
| Line 63: | Line 84: |
| /user/<user-id>/subscriptions -- list of (mailing-list URL, subscription URL) tuples. | /user/<user-id>/subscriptions - list of (mailing-list URL, subscription URL) tuples. |
| Line 65: | Line 86: |
| /user/<user-id>/settings -- dictionary of site-wide user settings (e.g. password). | /user/<user-id>/settings - dictionary of site-wide user settings (e.g. password). |
| Line 67: | Line 88: |
| /user/<user-id>/statistics -- retrieves statistical info. | /user/<user-id>/statistics - retrieves statistical info. |
| Line 69: | Line 90: |
| /subscription/<sub-id>/settings -- dictionary of settings for this list/user. PUT updates the settings. | /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, 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)
- subscriptions (approve, reject, defer)
h3. owner
- lists (create, modify, delete)
- subscriptions (create, modify, delete)
- users (create, modify, delete)
- statistics (read)
Original Use Case Proposal
This list contains the original use cases for the user <-> REST client interaction. Use cases that have been merged to the upper section have been marked strikethrough:
- 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 passwords for lists and for users
- 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.
Mass operations on users (subscribing/unsubscribing a list of e-mails)
Retrieving user statistics (# of posts, bounce status, etc.)
- Triggering a mass-catchup on the NNTP gateway.
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. There's no obvious standard format to use; designing a custom XML format also seems unnecessary. We decided at pycon08 that we should provide HTML and JSON differentiated by extensions .json and .html and for resources that make sense internationalized we could even do jp.html and so on. Also taking the recommendation of Leonard Richardson we will also honor the representation request in the Accept and Accept-Language headers.
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. 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
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