|
Size: 7298
Comment:
|
Size: 6084
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| #pragma page-filename DEV/versions/7962718 | #pragma page-filename DEV/versions/7962761 |
| Line 17: | Line 17: |
| * '''identity''' (create, modify) | * '''identity''' (create, modify, delete) |
| Line 43: | Line 43: |
| === 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: |
[[DEV/Original Use Cases]] == Principles == We use JSON. Libraries are available for most relevant programming languages and it's reasonably human-readable. |
| Line 46: | Line 48: |
| * 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: |
{{{{#!wiki important Also taking the recommendation of Leonard Richardson we will also honor the representation request in the {{{Accept}}} and {{{Accept-Language}}} headers. }}}} |
| Line 65: | Line 52: |
| * HTML * An existing XML format for representing data structures, such as XML-RPC's serialization. * A custom-designed XML format. * [[http://www.json.org/|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. 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. {{{#!wiki important We will use JSON }}} |
[[DEV/Initial Considerations]]<<BR>><<BR>><<BR>><<BR>><<BR>><<BR>><<BR>><<BR>> |
| Line 88: | Line 61: |
| || TODO: What does it list? | || List all top-level URLS <<BR>> |
| Line 91: | Line 64: |
| || TODO: What does it list? | || List all children URLS <<BR>> |
| Line 94: | Line 67: |
| || Return Mailman and Python version, read-only | || Return Mailman and Python version (read-only) |
| Line 97: | Line 70: |
| || List all plugins (name, description, author, version)<<BR>> | || List all plugins (name, description, author, version) <<BR>> |
| Line 99: | Line 72: |
| /sys/plugins/<plugin><<BR>> || Detailed info on a plugin<<BR>> |
/sys/plugins/<plugin> <<BR>> || Detailed info on a plugin <<BR>> |
| Line 103: | Line 76: |
| || List of statistics available | || List of statistics available below |
| Line 106: | Line 79: |
| || TODO: What does it list? | || Show lists by activity (performance, tuning aspects) <<BR>> |
| Line 109: | Line 82: |
| || TODO: What does it list? | || Show comparison of lists activity within the same domain <<BR>> |
| Line 111: | Line 84: |
| /stats/list || TODO: What does it list? |
/stats/lists || list all lists within the domain <<BR>> |
| Line 114: | Line 87: |
| /stats/users || TODO: What does it list? |
/stats/lists/<list-id> || Show list activity (new messages per day, replies to new messages same day) == /stats/users/ || * Top Ten Senders * Top Ten Contributers * Show a list of all users |
| Line 118: | Line 96: |
| || TODO: What does it list? | || * Number of posts per site * Number of posts per domain * Number of posts per list * Bounces per mail-address |
| Line 121: | Line 102: |
| || TODO: What does it list? | || List of preferred email-addresses (e-Mail, Full name) <<BR>> |
| Line 123: | Line 104: |
| /users/<username> || TODO: What does it list? |
/users/<user-id> || All information related to that person <<BR>> |
| Line 126: | Line 107: |
| /subscriptions/ || TODO: What does it list? |
/users/<user-id/<setting> || Specific settings related with a person (identity, MIME-settings, Vacation, etc.) <<BR>> |
| Line 129: | Line 110: |
| /subscriptions/ || TODO: What's beneath? |
/members/ || A list of all members (address, mailinglist, role) <<BR>> == /members/... || membership management (moderated, unsubscribe, etc.) <<BR>> |
| Line 133: | Line 117: |
| || TODO: What's beneath? | || A list of all email-addresses the system knows about <<BR>> == /addresses/<address> <<BR>> || information on an address (when was it validated, link to the user associated with it, etc.) <<BR>> |
| Line 136: | Line 123: |
| || returns list of (mailing list name, URL, public/private flag) tuples. POST is used to create a new list and redirect | || returns list of list-ids (mailing list name, URL, public/private flag) tuples. |
| Line 145: | Line 132: |
| || TODO: What does it list? | || List all domains within the site (hostname, web hostname, description, contact address) <<BR>> == /domains/<domain-id> <<BR>> || Manage that domain <<BR>> |
| Line 148: | Line 138: |
| || A list of all messages? No... | || List of all URLs below <<BR>> |
| Line 150: | Line 140: |
| /messages/<message-id> || TODO: What does it list? |
/messages/ids/ <<BR>> || A list of all message-ids == /messages/ids/<message-id> || Message specific info: Sender, Recipient, Date, Subject, Size <<BR>> == /messages/hashes/ <<BR>> || A list of all message-hashes <<BR>> == /messages/hashes/<message-hashes> <<BR>> || List of all message-hashes (see: [[DEV/Stable URLs]]) == /policies/<<BR>> || General policy for all lists on the site<<BR>> == /policies/domains/ || List of domains whose policy differs from the general site policy<<BR>> == /policies/domains/<domain><<BR>> || A domain specific policy <<BR>> == /policies/lists/<<BR>> || List of lists whose policy differs from the general site policy == /policies/lists/<list> || A list specific policy <<BR>> |
| Line 153: | Line 167: |
| === OLD === {{{#!table '''URL <<BR>>''' || '''Action''' == / || ??? == /list/ || returns list of (mailing list name, URL, public/private flag) tuples. <<BR>>POST is used to create a new list and redirect == /list/<list-id>/ || XXX what's useful to return here? <<BR>>links to settings and subscriptions, maybe? == /list/<list-id>/subscriptions || list of (e-mail address, subscription URL) tuples. <<BR>>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 <<BR>> || 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. }}} |
[[../Initial URL design|Initial URL design]] |
| Line 201: | Line 176: |
* '''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. |
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, delete)
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
Principles
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 |
| / | List all top-level URLS |
| /sys | List all children URLS |
| /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 below |
| /stats/site | Show lists by activity (performance, tuning aspects) |
| /stats/domain | Show comparison of lists activity within the same domain |
| /stats/lists | list all lists within the domain |
| /stats/lists/<list-id> | Show list activity (new messages per day, replies to new messages same day) |
| /stats/users/ | * Top Ten Senders * Top Ten Contributers * Show a list of all users |
| /stats/users/<username> | * Number of posts per site * Number of posts per domain * Number of posts per list * Bounces per mail-address |
| /users/ | List of preferred email-addresses (e-Mail, Full name) |
| /users/<user-id> | All information related to that person |
| /users/<user-id/<setting> | Specific settings related with a person (identity, MIME-settings, Vacation, etc.) |
| /members/ | A list of all members (address, mailinglist, role) |
| /members/... | membership management (moderated, unsubscribe, etc.) |
| /addresses/ | A list of all email-addresses the system knows about |
| /addresses/<address> |
information on an address (when was it validated, link to the user associated with it, etc.) |
| /lists/ | returns list of list-ids (mailing list name, URL, public/private flag) tuples. |
| /lists/<list-id> | lists list homepage info |
| /list/<list-id>/<setting> | Arbitrary <settings> that configure a list |
| /domains/ | List all domains within the site (hostname, web hostname, description, contact address) |
| /domains/<domain-id> |
Manage that domain |
| /messages/ | List of all URLs below |
| /messages/ids/ |
A list of all message-ids |
| /messages/ids/<message-id> | Message specific info: Sender, Recipient, Date, Subject, Size |
| /messages/hashes/ |
A list of all message-hashes |
| /messages/hashes/<message-hashes> |
List of all message-hashes (see: DEV/Stable URLs) |
| /policies/ |
General policy for all lists on the site |
| /policies/domains/ | List of domains whose policy differs from the general site policy |
| /policies/domains/<domain> |
A domain specific policy |
| /policies/lists/ |
List of lists whose policy differs from the general site policy |
| /policies/lists/<list> | A list specific policy |
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?
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.
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