[Pki-devel] thinking about the proposed RESTful interface

[Ade Lee]

Endi recently brought up the question as to whether we should change the
conventions we have proposed for the REST interface URI mapping for
resources.

Proposal A:
The current proposed convention is to use plural for collections, and
singular for individual resources, as follows:
GET /pki/keyrequests  -- get collection (list) of key requests
GET /pki/keyrequest/X -- get key request for id X

Proposal B:
Endi proposes to simply put everything under the plural, as follows:
GET /pki/keyrequests  -- get collection (list) of key requests
GET /pki/keyrequests/X -- get key request for id X

A good place to see even more suggested alternatives is here: 
http://redrata.com/restful-uri-design/

************************
Proposal A
Pros: 
1. There is no convention in general on how these things should be
named.  Proposal A was selected because it is the convention employed by
a default configuration in Rails.
2.  What we expect to return -- a collection of key requests (which is
just a list of urls with some abbreviated data about the requests), and
the request data itself -- are two different entities.
Using /keyrequests and /keyrequest makes that explicit.
3.  To me, this just seems more intuitive.  More on that can be seen
here: 
http://blog.roberthahn.ca/articles/2007/04/06/url-design/

Cons:
1.  The URL is not hackable -- ie. you need to handle
GET /pki/keyrequest  where no $id is provided.  You could return an
error - or you could redirect to /pki/keyrequests.  We should decide
which is most appropriate.

*************************
Proposal B:
Pros:
1. The URL is hackable.  That is - if I take /pki/keyrequests/id and
hack off id, then I still get a valid URL.

Cons:
1. You may want to have queries that look like the following:
GET /pki/keyrequests/recent
GET /pki/users/admins

In these cases, I am looking for collections of users matching a
particular characteristic.  For example, I am looking for the collection
of users that are admins, rather than the user named "admins".  Proposal
B has the possibility of name conflict , whereas proposal A does not.

In proposal A, it is immediately clear whether I want a collection
(named or otherwise) or an individual resource - and I can be free to
qualify my collections as I see fit.
 
********************
Based on the above, I'm inclined to stick with Proposal A.  In the link
above, they mentioned some other alternatives - which IMHO - are overly
complicated.

But I'm opening this for debate.  Let the sparring begin!

Ade