[Pki-devel] Proposed RESTful interface to dogtag

Tue Oct 18 02:33:03 UTC 2011

On 10/17/2011 10:00 PM, Jack Magne wrote:
> 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.

We are all learning this stuff, and I had a little too narrow a view 
before this discussion.  One other resource I read states that you 
should use POST for anything that would not be idempotent:  thus,  PUT 
to create makes sense if you know the name to PUT it into, but you would 
use POST for creating a new identifier.  So, I think that agrees with 
what you are saying.

So, yeah, I think you would PUT a key, assuming that the the PUT 
provides also the name of the key.  You would POST a CSR to get a 
Certificate (in a simplified view)  as the Certificate would get a 
Serial number, and that would be the unique ID.

I guess for creating a user, it would depend on if you were assigning 
the numeric UID whether it would be POST of a PUT.

I've a lot to learn about the Domain model here, so I'll let myself be 
guided by you guys as far as what the appropriate behavior of the 
business objects should be.

>
>
>
>
>>
>> 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
>>    
>
>
>
> _______________________________________________
> 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/d21f6fc1/attachment.htm>