Differences between revisions 3 and 37 (spanning 34 versions)

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

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.

DEV/Initial Considerations

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/list	list all lists within the domain
/stats/list/<list-id>	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

Initial URL design

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

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

-  ⇤ ← Revision 3 as of 2008-02-08 08:49:34 → 
  Size: 3411
  Editor: amk@amk
  Comment:
+   ← Revision 37 as of 2009-04-01 13:57:29 → ⇥
  Size: 4983
  Editor: p@state-of-mind
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 1:
-#pragma page-filename DEV/versions/3276825
+#pragma page-filename DEV/versions/7962745
 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, 
or a fancy GUI application, or administrative scripts,
+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.
<<BR>>
 Line 11:
- * Messages.
+ * Messages
 Line 13:
- * 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.)
+=== 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]]
-Line 25:
+Line 46:
-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:
+We use JSON.  Libraries are available for most relevant programming languages and it's reasonably human-readable.
<<BR>>
{{{{#!wiki important
Also taking the recommendation of Leonard Richardson we will also honor the representation request in the {{{Accept}}} and {{{Accept-Language}}} headers.
}}}}
-Line 28:
+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.  
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
+[[DEV/Initial Considerations]]<<BR>><<BR>>
-Line 42:
+Line 56:
-/ -- Returns Mailman version.
+{{{#!table
'''URL <<BR>>'''
|| '''Action'''
==
/
|| List all top-level URLS<<BR>>
==
/sys
|| List all children URLS<<BR>>
==
/sys/version
|| Return Mailman and Python version (read-only)
==
/sys/plugins
|| List all plugins (name, description, author, version) <<BR>>
==
/sys/plugins/<plugin> <<BR>>
|| Detailed info on a plugin <<BR>>
==
/stats/
|| List of statistics available below
==
/stats/site
|| Show lists by activity (performance, tuning aspects) <<BR>>
==
/stats/domain
|| Show comparison of lists activity within the same domain <<BR>>
==
/stats/list
|| list all lists within the domain <<BR>>
==
/stats/list/<list-id>
|| Show list activity (new messages per day, replies to new messages same day)
==
/stats/users
|| TODO: What does it list?
-Line 44:
+Line 93:
-/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.
+ * Top Ten Senders
 * Top Ten Contributers
==
/stats/users/<username>
|| TODO: What does it list?
==
/users/
|| TODO: What does it list? <<BR>>List of all users <<BR>>
==
/users/<username>
|| TODO: What does it list? <<BR>>
==
/subscriptions/
|| TODO: What does it list? <<BR>>
==
/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? <<BR>>List all lists within a domain? <<BR>>Configure global/default settings of all lists within the domain? <<BR>>
==
/messages/
|| A list of all messages? No...
==
/messages/<message-id>
|| TODO: What does it list? <<BR>>Header-Info: Sender, Recipient, Date, Subject, Size <<BR>>
}}}
[[../Initial URL design|Initial URL design]]
-Line 47:
+Line 134:
-/list/<list-id>/ -- XXX what's useful to return here?  links to settings and subscriptions, maybe?
+== 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.
-Line 49:
+Line 138:
-/list/<list-id>/subscriptions -- list of (e-mail address, subscription URL) tuples.
+ * '''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?
-Line 51:
+Line 142:
-/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.
+ * '''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.