[Pki-devel] TPS REST interface design

[Ade Lee]

On Mon, 2013-07-01 at 12:30 -0500, Endi Sukma Dewata wrote:
> On 7/1/2013 11:51 AM, Endi Sukma Dewata wrote:
> >  From http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.5:
> >> The POST method is used to request that the origin server accept the
> >> entity enclosed in the request as a new subordinate of the resource
> >> identified by the Request-URI in the Request-Line. POST is designed
> >> to allow a uniform method to cover the following functions:
> >>
> >> - Annotation of existing resources;
> >> - Posting a message to a bulletin board, newsgroup, mailing list,
> >>   or similar group of articles;
> >> - Providing a block of data, such as the result of submitting a
> >>   form, to a data-handling process;
> >> - Extending a database through an append operation.
> >>
> >> The actual function performed by the POST method is determined by the
> >> server and is usually dependent on the Request-URI. The posted entity
> >> is subordinate to that URI in the same way that a file is subordinate
> >> to a directory containing it, a news article is subordinate to a
> >> newsgroup to which it is posted, or a record is subordinate to a
> >> database.
> >
> > Adding a new user or profile into a collection would be analogous to the
> > above examples.
> 
> Just to clarify, when adding a file into a directory we know the file 
> name already. Still, this is given as an example of a POST operation. 
> So, knowing the ID ahead of time is irrelevant to picking PUT vs. POST 
> to create a resource.
> 
Just to be clear, it is perfectly RESTful to create an interface using
only GET and POST.  POST can literally be used for pretty much anything
and still be restful.  The question is more one of restful practice.
Its far more intuitive and friendly to use the other verbs PUT and
DELETE, even though there may be some clients that do not support these
operations.

As to this specific use of PUT vs. GET, I've seen best practice
guidelines that advocate both scenarios.  I am, however, most convinced
by the idea that the POST allows the server more flexibility in
selecting the Location.

An example I saw of using PUT was for a user being able to store their
personal set of favorites.  For this case, it is entirely appropriate
that the user controls the location URL.  

In our case, what we are creating are server resources and we want
control over that.

So, point conceded.