Hi Michal,
yes, these are all good questions; just to add to the options: there's
also a door #4: PATCH edit instructions to the resource's URL.
I find #1 very problematic, since it seems too easy to make disastrous
mistakes and way too chatty; for #2 and #3, I'd rather not continue
relying too much on request parameters, I think we already overuse them
in the DC API
There's a draft for a JSON format for editing resources[1] - while the
full thing seems overkill, I like how doing this very precisely
specifies what changes you want. It's also fairly friendly for clients,
as they can build one of these objects up as their user is making
changes.
For example, to change the name of an instance, you'd do
PATCH /api/instances/inst0
[
{ "op": "replace", "path": "/name", "value": "new_name" }
]
David
[1] http://tools.ietf.org/html/draft-ietf-appsawg-json-patch-06
On Tue, 2012-11-27 at 12:47 +0100, Michal Fojtik wrote:
> Hi,
>
> I'm trying to figure out what would be the best way to to handle resource
> updates. For example, updating an instance named [DTACLOUD-366, DTACLOUD-345].
> For now, in Deltacloud we don't support the 'update' operation, however,
> some clouds like FGCP (and partially OpenStack/RHEV-M/EC2) do support this
> feature.
>
> There are three possible scenarios:
>
> 1. Using 'PUT' (PUT /api/instances/inst1):
>
> The request body will contain full representation of the resource (so
> basically we will replace the old resource with a new one).
>
> 2. Using 'PATCH' (PATCH /api/instances/inst1?name=new_name):
>
> In this case, you can choose what attributes you want to update as query
> parameters. It also seems to be a more REST-friendly approach when you're
> updating just a single attribute.
>
> 3. Using 'POST' (POST /api/instances/inst1/edit?name=new_name):
>
> Basically the same thing as 2), but instead of the PATCH HTTP method, we
> can use the
>
> 'POST' method on the 'edit' action. The dark side of this approach is that
> we are poisioning the URL namespace with '/edit' (that is, the instance ID
> can't be set to 'edit').
>
> I known that in the CIMI, updating is done by combination of 1). and 2)
> (PUT + '/edit'), which could be our option 4). However, I don't like this
> approach, because PUT is meant to replace the whole resource and does not
> fit well when you're updating just a single attribute.
>
> The second part of implementing the 'update' operation is to add support
> for it into drivers. I think the simpliest way is:
>
> def update_instance(credentials, instance_id, opts={})
> # safely do; driver.update_attrs(...) ;end
> end
>
> The last part is to mark what attributes are allowed for the update. I
> think this will vary from one provider to another. We can both advertise
> this usingthe OPTIONS method or just simply return a validation error to
> the client when he tries to update a read-only attribute. (Or we can use
> the database to store them....)
>
> My personal preference is 2) :-), but I just want to start a discussion
> about this before somebody starts writing the code (I know that there are
> milions of blogs/articles about updating resources, the problem is what to
> choose and what will fit to us ;-)
>
> Cheers,
>
> -- Michal
>
