On 1/5/2012 10:25 PM, Ade Lee wrote:
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/
According to this article we should use lower case and minus signs to separate the words. So intead of: /pki/token/sessionKey /pki/keyrequests we use: /pki/token/session-key /pki/key-requests I think it's more readable. Also suggested in the article we can use the singular form as prefix for the ID. So instead of: /pki/certificates/$id /pki/certificates/ocsp we use: /pki/certificates/certificate-$id /pki/certificates/ocsp It helps to avoid clashes between $id and other keywords.
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.
If we use plural->singular scheme like this: /pki/key-requests/key-request-$id it will make it explicit too.
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/
According to this article we might be able to change: /pki/certificates/$id/details /pki/certificates/$id/status with this: /pki/certificates/$id;details /pki/certificates/$id;status I think we should use / only when the item above it is a container.
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.
The main reason is simplicity, with a single URL you can find everything related to users under /pki/users (think of it like a folder of files). You only need to configure the security for one URL. Also, there's less chance of typos.
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.
As mentioned earlier we can also use the prefix to avoid conflicts: /pki/key-requests/request-$id /pki/key-requests/recent /pki/users/user-admins --> user named admins /pki/users/group-admins --> group of admin users We can also use the prefix to describe the id: /pki/users/user-jsmith /pki/users/uid-512 /pki/users/employee-83726 They all point to the same user.
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.
Functionally, either option will work just fine, so I don't have strong objections, but I think single URL is more intuitive. In some languages there's no difference between singular & plural forms, in that case there's no choice but to use one URL. -- Endi S. Dewata