[Pki-devel] thinking about the proposed RESTful interface

[Adam Young]

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 at 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.