[Pki-devel] Proposed RESTful interface to dogtag

Tue Oct 18 02:00:21 UTC 2011

On 10/17/2011 05:35 PM, Adam Young wrote:
> On 10/17/2011 08:10 PM, Jack Magne wrote:
>> On 10/17/2011 01:18 PM, Ade Lee wrote:
>>> Hi all,
>>>
>>> I tried to put this on the dogtag wiki, but it did not seem to work.
>>> Will chat with Matt.
>>>
>>> In the meantime, here is a copy for you guys to look at and comment on.
>>> It has most everything except the installation servlets and token
>>> operations (for which I need to think about the object model).  If you
>>> look at the mapped servlets, you'll get a sense of what operations are
>>> covered in each URL mapping.
>>>
>>> This is a first cut -- hopefully a good starting point for discussion.
>>> So please comment away!
>>>
>>> Ade
>>>
>>>
>>>    
>>>
>>>
>>> _______________________________________________
>>> Pki-devel mailing list
>>> Pki-devel at redhat.com
>>> https://www.redhat.com/mailman/listinfo/pki-devel
>>>    
>> Thanks Ade. Just a few questions after having a look.
>>
>> 1. I noticed we have the following key related resources:
>>
>>
>> PUT         /pki/key     "Add a key"
>>
>> POST      /pki/key      "Modify a key"
>>
>> In my quick readings, it appeared that the POST method was favored 
>> for creating brand new resources where PUT was used to modify 
>> existing ones?
> I think you have it backwards.  PUT is the normal way for creating 
> things. The POST operation is very generic and no specific meaning can 
> be attached to it.  In general, use POST when only a subset of a 
> resource needs to be modified and it cannot be accessed as its own 
> resource; or when the equivalent of a method call must be exposed.
>
> http://developer.mindtouch.com/REST/REST_for_the_Rest_of_Us  says this 
> about POST:
>
> " usually either create a new one, or replace the existing one with 
> this copy, where as POST is kinds of a catch all.  "
>
> We could possibly use PUT for both add and modify if we wanted.
>
My bad. I guess I chose to read a conflicting article on this subject:

http://www.ibm.com/developerworks/webservices/library/ws-restful/

where it says the following:

    * To create a resource on the server, use POST.
    * To retrieve a resource, use GET.
    * To change the state of a resource or to update it, use PUT.
    * To remove or delete a resource, use DELETE.

Perhaps I was further thrown off about the discussions I've seen about 
the idempotence property of PUT, whereby if you replay the same request 
more than once, you get the same result as the first time. Where in 
POST, if you repeat the exercise multiple times, you will get a list of 
new resources. Perhaps you could speak a little to that subject.

I think I see now why he would chose PUT to create a key, because PUT 
replaces the entire resource, and POST can be used to replace part of a 
resource. If we were to modify a key or a request for a key, I'm 
guessing we would not replace the entity entirely.

>
> I tend to favor making objects immutable, and to replacing whole 
> objects when possible.  However, I know that is not always possible, 
> especially when working with a pre-existing API.  So I'd say lets try 
> to stick to PUT semantics where possible, but deliberately use POST 
> when we are making finer grain API calls.
>
>>
>> I also noticed that you have two GET versions of "pki/key". Is that 
>> kind of duplication encouraged? Or is that really just the same api 
>> entity with different input payloads?
>>
>> 2. You suggested I take a look at some of the TKS TokenServlet stuff. 
>> I noticed that we have a simple short list of servlets that appear to 
>> return very short lived resources. Examples being, session keys , 
>> encrypted data , and a block of randomly generated data.
>>
>> I would imagine it would be a POST op like something as follows:
>>
>> POST /pki/tks/sessionKey   , which would return a link to the key 
>> itself? But does it make sense to have a "resource" for something so 
>> short lived, or does this concept even belong in such a design?
>
> In general, REST works best if the service is stateless.  Session 
> based information should be minimized if possible.
Perhaps REST is not the way to go in the token space due to the nature 
of the beast.

>
>
>>
>> 3. I was just curious about the Java back-end for this design. Will 
>> we be using the JAX-RS stuff that provides annotations in the java 
>> code in order to hook all of this up?
>
> I am not a fan of annotations.  Under other circumstances, I might be 
> prone to say "well, that is the way of the world" and go with JAX-RS, 
> but since we don not yet have a set of Entity objects that would drive 
> the JAX-RS, I am more prone to  look at other alternatives.  THere are 
> good libraries for serializing to JSON or XML  that should be 
> sufficient for our needs, and that will keep us from having to make 
> our API  conform to JAX-RS.  So my inclination is to say no to JAX-RS 
> to start.
>
>>
>> thanks,
>> jack
>

Thanks for the clarifications!
>
> Ade's document has founds its way into the wiki world:
>
> http://pki.fedoraproject.org/wiki/Dogtag_Future_Directions
>
>
> I might have made some Wiki errors in translation.   If this 
> contradicts Ade's spreadsheet, assume the spreadsheet is Canonical.
>
>
>
>
> _______________________________________________
> Pki-devel mailing list
> Pki-devel at redhat.com
> https://www.redhat.com/mailman/listinfo/pki-devel
>    

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pki-devel/attachments/20111017/ba7f7e18/attachment.htm>