[Pki-devel] TPS REST interface design

[Endi Sukma Dewata]

On 6/29/2013 2:16 PM, Ade Lee wrote:
> One thing I just noticed though is the operation to add a token.
> You have POST /tokens passing in the tokenId.
>
> POST /tokens is only used when creating a resource when the URL of the
> resource is unknown -- ie. it will be specified by the server.  An
> example of this is POST /certrequests which returns the URL of the
> request /certrequests/0xf00 where 0xf00 is the request ID as assigned by
> the server.

That is one way to use POST, but in general it doesn't always have to be 
that limited. Consider the ID as an optional parameter. You can specify 
it, but it's not specified the server could generate a new ID 
automatically (not that we want to do that for this case). For the 
client it would be easier to use the same operation to create a new 
entry, with or without the ID. The operation that will work for both 
cases is POST-ing into the collection.

I don't think this is violating any REST guidelines. It's also 
consistent with the add operation for the existing user and group resources.

> In this case, the token ID is what is being passed in.  So we know the
> resultant  URL when the resource is created.  There are two options
> instead:
>
> a) PUT  /tokens/tokenID
> b) POST /tokens/tokenID
>
> My preference is a) but of course the advantage of (b) is that there is
> a distinction between an ADD and a modify operation.
>
> The same comment applies to all the ADD operations in the design.

The problem with (a) is that without ETag there's a risk overwriting an 
existing token, and there's no warning or error message when that 
happens. While ETag is desired, it should be optional (can we guarantee 
all clients will support ETag?) and may not get implemented right away. 
If we POST to the collection the server can reject it if the entry 
already exists. Also, naturally an add operation is not idempotent, so 
we should not use PUT.

Option (b) is a little weird because usually we expect the resource 
would already exist when we POST. POST-ing to the collection is fine 
because the collection always exists.

-- 
Endi S. Dewata