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.