[Pki-devel] Proposed RESTful interface to dogtag

[Adam Young]

On 10/17/2011 08: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.
>
>
> 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.

And...now I am going to contradict that.  I see that the general wisom 
is to use POST if you want the server to create the unique ID for you, 
and PUT if you know it a-priori....so we will probably be using POST for 
things like Cert creation where the Serial number comes from the server.

>
>>
>> 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.
>
>
>>
>> 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
>
>
> 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/9f2c340b/attachment.htm>