#pragma page-filename DEV/versions/3276802
= 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 ==
=== 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.
=== moderator ===
* '''messages''' (approve, reject, discard, defer)<
> Handle pending requests.
* '''subscriptions''' (approve, reject, defer)<
> Handle subscription tasks.
=== 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
[[../Original Use Cases|Original Use Cases]]
== Principles ==
We use JSON. Libraries are available for most relevant programming languages and it's reasonably human-readable. <
>
{{{#!wiki important
Accept-Language
Also taking the recommendation of Leonard Richardson we will also honor the representation request in the `Accept` and `Accept-Language` headers.
}}}
[[../Initial Considerations|Initial Considerations]]<
> <
> <
> <
> <
> <
> <
> <
>
== URL Space ==
Unless otherwise specified, all these URLs return a data structure encoded as JSON.
{{{#!table
'''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/ <
>
|| 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/
|| 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/
|| * 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/
|| All information related to that person
<
>
==
/users/
|| 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/ <
>
|| 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/
|| lists list homepage info
==
/list//
|| Arbitrary that configure a list
==
/domains/
|| List all domains within the site (hostname, web hostname, description, contact address)
<
>
==
/domains/ <
>
|| Manage that domain
<
>
==
/messages/
|| List of all URLs below
<
>
==
/messages/ids/ <
>
|| A list of all message-ids
==
/messages/ids/
|| Message specific info: Sender, Recipient, Date, Subject, Size
<
>
==
/messages/hashes/ <
>
|| A list of all message-hashes
<
>
==
/messages/hashes/ <
>
|| List of all message-hashes (see: [[../Stable URLs|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/ <
>
|| A domain specific policy
<
>
==
/policies/lists/ <
>
|| List of lists whose policy differs from the general site policy
==
/policies/lists/
|| A list specific policy
<
>
}}}
[[../Initial URL design|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.
Unless the REST interface is designed to replace the Browser interface, it shouldn't expected a user can navigate without error by manufacturing urls, no? In either case /list/mailman-developers/ is preferable for seeing where your current location via the url. 123456 is uninformative.
Unless there is some unfailing reason to disallow it there is no reason to disallow names like foo/bar would just be escaped to foo%2Fbar. Another option is to have a urlsafe name generator that replaced unsafe characters with a '-'. then the name 'foo-bar' could be used while preserving readability in the url
----
* [[DEV/Initial Considerations|Initial Considerations]]
* [[DEV/Initial URL design|Initial URL design]]
* [[DEV/Original Use Cases|Original Use Cases]]
* [[DEV/restserver-branch|restserver-branch]]
----
<>