[Pki-devel] thinking about the proposed RESTful interface

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