[Pki-devel] TPS REST interface design

[Endi Sukma Dewata]

On 7/1/2013 11:37 AM, Ade Lee wrote:
>> I also added a Change Profile State operation:
>> http://pki.fedoraproject.org/wiki/TPS_REST_Interface#Change_Profile_State
>>
> The way this is written, it looks like you are just doing a POST to
> the /tps/rest/profiles/<ProfileID> and passing in "action" as a
> parameter.  Thats not very RESTful at all.
>
> I think we want:
> /tps/rest/profiles/{id}/{action}
>
> where {action} is approve etc.  This is also consistent with how we have
> done this for cert-requests etc. as well.

This is where I'd like to see the current API changed. These actions 
(e.g. approve, enable) are not resources or collections. None of the 
other operations (GET, PUT, DELETE) make sense on actions.

On the other hand, using POST to process data is a valid & RESTful 
operation. POST request should be sent to a resource, and the resource 
that we want to handle these actions is the target of the action (i.e. 
profile).

According to POST definition:
* The actual function performed by the POST method is determined by the 
server and is usually dependent on the Request-URI.
* The action performed by the POST method might not result in a resource 
that can be identified by a URI.
* Example:
   - Providing a block of data, such as the result of submitting a
     form, to a data-handling process;

According to http://www.ietf.org/rfc/rfc2616.txt (9.6 PUT):
> The URI in a POST request identifies the resource that will handle
> the enclosed entity. That resource might be a data-accepting process,
> a gateway to some other protocol, or a separate entity that accepts
> annotations.

Also, POST-ing to /tps/rest/profiles/{id} will be more future-proof in 
case we add/remove actions later.

-- 
Endi S. Dewata