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
On 01/05/2012 11:25 PM, Ade Lee wrote:
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
_______________________________________________ Pki-devel mailing list Pki-devel@redhat.com https://www.redhat.com/mailman/listinfo/pki-devel
I like the idea of using the same URL for singular as for plural. I'd prefer the Singular, as that is what DB tables tend to use as well, but other than that I think that Endi's proposal is right on.
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
participants (3)
-
Adam Young -
Ade Lee -
Endi Sukma Dewata