10:25 p.m.
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
7:46 a.m.
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(a)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.
2:07 p.m.
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
4493
days inactive
4498
days old
2 comments
3 participants
participants (3)
-
Adam Young -
Ade Lee -
Endi Sukma Dewata