[jboss-as7-dev] Detyped and REST configuration API

[David M. Lloyd]

On 11/30/2010 11:37 AM, Brian Stansberry wrote:
>>> In general, my concern about the approach you're outlining is it feels
>>> RPCish and not RESTful. I'm actually more comfortable with RPC, but we
>>> have a requirement to provide a REST interface and I'm concerned about
>>> straying so far from REST principles that the REST interface becomes an
>>> unmaintainable hack.
>>
>> I'm not worried about that.  We can support GET for reading (of course),
>> PUT for adding (in SOME cases), LIST for certain read tasks, DELETE for
>> removal (in SOME cases), and POST for nontrivial updates.  It's
>> REST-enough for me.
>>
>
> What's with the big scary capital "SOME cases"? Why not a big scary
> capital "MOST cases"? (IOW what am I missing here?)

Well I still believe that a generic POST-y update mechanism is the 
*simplest* solution, and I'm a big fan of simple.  If we want to extend 
it a little and say, there's a generic *add* mechanism, and a generic 
*delete* mechanism, for which subsystems can register handlers for 
different address types, I'd be OK with that.

For example, the threads subsystem could say, "Hey, I've got a handler 
here which handles adds (PUTs) to subsystem/jboss.thread/pool", or "I've 
got a handler which handles DELETEs to subsystem/jboss.thread/pool/xxxx".

On the other hand according to RFC2616, PUT is supposed to only be used 
to modify, or create a resource (but only if the caller is choosing the 
new identifier).  POST is what you'd use to add (as they say, 
"annotate") a subitem under an existing parent item where the result URI 
may differ from the request URI (as in, server picks ID).

I'm still pretty sure that a generic PUT-y update operation won't be 
nearly as easy to do consistently - that is unless we make an update 
include the target address *plus* the field(s) being updated, and then 
have a registration mechanism which defines the possible update 
combinations somehow.  For example, users would never be allowed to 
update the internal ID of a deployment.  Perhaps we should somehow 
include the attribute structure directly in the address for updates?

Another thing to consider is that PUT is supposed to be idempotent, so 
that makes it more complicated across the board I guess, but this gets 
into the realm of REST religion so I'll leave that to other viewpoints.

> The POST for the non-trivial updates is going to end up being pretty
> non-RESTy; it won't just be posting back the element fields, it will
> need to include a parameter that identifies the update type.
>
> I'm no REST purist; that's probably OK. I wouldn't mind having a REST
> purist argue with us a bit about this though.

Well, there's another way around the REST purity thing.  Use PUTs or 
POSTs to create the updates, which return URLs to the things which were 
modified.  This is in line with the notion of building up complex update 
plans I suppose, and also fits in with the notion of including the 
target field(s) in the update I guess, if we go that route.

-- 
- DML