[Cosmo-dev] [proposal] Cosmo Management Protocol 0.4

[Travis Vachon]

Hi folks

To support the work I'm doing transitioning the Cosmo Administrative UI
away from Struts, I would like to propose several extensions to the
Cosmo Management Protocol. These extensions will allow us to preserve
the current administrative interface in the new Spring MVC/ Dojo based UI.

I would like to propose three specific changes to the protocol (a
version that may be more readable can be found at
http://wiki.osafoundation.org/bin/view/Journal/CMPZeroDotFourProposal):

1) POST based user deletion

To support browsers (specifically Safari) that do not support the DELETE
method in XMLHttpRequests, I would like to propose

"POST /cmp/user/{username}/delete"

as a synonym for

"DELETE /cmp/user/{username}".


In addition, to provide better performance for multi-user deletion, I
would like to propose

"POST /cmp/user/delete"

with a message body like

"user=user1&user=user2&...&user=userN"

as a synonym for

"DELETE /cmp/user/user1"
"DELETE /cmp/user/user2"
...

"DELETE /cmp/user/userN"




2) Additional user information

To support an administrative interface identical to our current
interface, I would like to propose additional information in the
response to GET /cmp/users and GET /cmp/user/{username}.

Specifically, I propose we return 3 new pieces of information for each user:
   * Date Created (Date) (XML tag <created>)
   * Date Modified (Date) (XML tag <modified>)
   * Administrator (Boolean) (XML tag <administrator>)




3) User list paging and sorting

I would like to propose 4 new query parameters for the command "GET
/cmp/users":
   * ps (page size, ie, number of users per page, default=all users)
   * pn (page number to return based on ps, so, and st, default=1)
   * so (sort order, [ascending | descending], default=descending)
   * st (sort type, [firstname | lastname | username | administrator |
email | created | modified], default=username)

In addition, we will support the collection paging extensions to the
atom protocol: http://www.ietf.org/html.charters/atompub-charter.html

For example (thanks to Brian Moseley for this example), the url

http://localhost:8080/cosmo/cmp/users?ps=25&pn=2

on a Cosmo server with 625 users will return:
...
    <users>
      <link rel="first"
            href="http://localhost:8080/cosmo/cmp/users?ps=25" />
      <link rel="previous"
            href="http://localhost:8080/cosmo/cmp/users?ps=25&pn=1" />
      <link rel="next"
            href="http://localhost:8080/cosmo/cmp/users?ps=25&pn=3" />
      <link rel="last"
            href="http://localhost:8080/cosmo/cmp/users?ps=25&pn=25" />
      ...
    </users>
...



None of these changes should break backwards compatibility, and I
believe I have chosen defaults to the paging and sorting parameters so
that current commands will return the same responses (with, of course,
the new user details from item 2 and the atom extension information).

I am currently working on these changes in my sandbox, and, if there are
no major objections, will submit a patch as soon as it is ready. Please
feel free to make comments in this thread, or on the wiki page.

Thanks,

Travis