[Pki-devel] thinking about the proposed RESTful interface

[Endi Sukma Dewata]

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