In other words, this resource can have one or more elements that act
as partial updates to the underlying (via {id}) full resource. I can
then code partial update 'smarts' into the server-side code (validate
the document has one or more of the approved update-able elements;
locate the original resource, update each approved element that
exists, update caches as required, etc.).

This allows for PUT/POST for the full resource as expected and still
provides support for partial updates without using PATCH/diff
semantics.

I like this from an implementation perspective - driving everything via
resources and the URI is powerful. However, when "many" properties can
be modified, the server-side implementation can begin to get very
kludgy.

Is update a noun or verb? (j/k). I can see how this could work however is this resource GET able?

Message 2 of 7
, Jan 2, 2008

Is 'update' a noun or verb? (j/k).

I can see how this could work however is this resource GET'able?

mike amundsen

LOL yeah. no verb allowed in my patterns, this resource will return 404/415 if you attempt a GET. however, doing the PUT usually returns a Location of the

Message 3 of 7
, Jan 2, 2008

LOL yeah. no verb allowed<g>

in my patterns, this resource will return 404/415 if you attempt a
GET. however, doing the PUT usually returns a Location of the updated
underlying resource that the client can then use for the GET. I like
this pattern because, along with making it relatively easy to support
partial PUTs, it also has the potential to create a audit log of the
updates. i've relied on this to create a simplistic change-log that
admins can review.

However, a rather nasty side-effect of this kind of pattern is that it
can create problems with the data integrity of the underlying
resource. I only allow partial updates on elements that are optional
and do not directly affect flow control. that way, users can't change
the state of the object in a way that invalidates it (vis-a-vis other
partial update elements from other parties). I have to take care to
keep the resource consistent and sometimes even have to create
resources that require more than one element in the partial update:

For flow-control items (i.e. change from "pending" to "approved") I
almost always create a new resource anyway. These are most often
critical state changes that need to be atomic and isolated anyway.
Finally, for relatively small or very dynamic resources, I find it's
better to force a full PUT and take advantage of ETags to prevent the
"Lost Update" problems.

To me, the use of XML is confusing, it leads to thinking of the resource in terms of a closed, well-formed document, coloring the decision. I think it s easier

Message 4 of 7
, Jan 2, 2008

To me, the use of XML is confusing, it leads to thinking of the
resource in terms of a closed, well-formed document, coloring the
decision.

I think it's easier to start by talking about forms and URL-encoded
updates, with XML being an alternative encoding. For that, I can find
a lot of interesting examples in the wild. (Ignore the fact that
hForms uses POST for now, think HTML 5 and PUT)

* I can create a form that will update all the values associated with
the resource, but also a form to update some of these values, or offer
both alternatives for the same resource. Is one better than the
other?

* I can allow the form to mark which part of the resource gets
updated, much the same way printed forms have an optional 'change of
address' part with a checkbox.

* I can pre-fill the form with existing values from the resource, and
just write over the resource from all the request parameters. But
sometimes, I would chose not to process missing values; account
setting pages use that when updating passwords, but ignoring empty
password fields.

(sigh - posted last reply offline to Assaf...) I see your point, your pattern has the server responding with PUT-able hForms that contain only the valid

Message 5 of 7
, Jan 2, 2008

(sigh - posted last reply offline to Assaf...)

I see your point, your pattern has the server responding with PUT-able
hForms that contain only the valid elements for partial PUTs. A bit
tricky, but I see how that's "hyperlinking..." and, thus RESTful.

And the ETag issue can be handled if the server will send a hidden
field with the ETag value and deal with it on the PUT as it would the
header.

You're replying off-list, not sure if it's intentional or accidental
(it happens to me all to often with rest-discuss)

On Jan 2, 2008 5:15 PM, mike amundsen <mca@...> wrote:
> From my perspective, the representation of the resource (in my
> examples XML) doesn't change the pattern. In my examples, the
> representation is just a medium (i rarely *store* data in XML anyway).
> I could be JSON, Atom, form-encoded, etc.
>
> Thinking about your example (and imagining HTML FORMS *and browsers*
> finally allow PUT) still leads me to the same conclusions. Partial
> updates are risky when you want to ensure the integrity of the object
> being updated. The risk goes up as you add more users to the system.

When it comes to forms, the server is in control of the exchange, so
it directs the client to that subset of values it find acceptable. So
in this particular example, the server finds the risk not to be an
issue, otherwise, it would serve a form with all the values. And so
far, this seems easier (for me) to test and implement than partial
resources of the form /resource/{id}/subset.

> To reduce the risk, I prefer to:
> - use only full PUT and use ETags to prevent updating a record that
> was already updated by someone else
> - using a new resource for updating sub-sections of the resource (PUT
> /resource/{id}/shippingaddress)
> - using atomic resources for optional, non-critical elements (PUT
> /resource/{id}/favorite-color)
>
> BTW - in all three examples, i still use the ETag to ensure update integrity.

So would I, except that hForms don't support ETag, but there are ways
around it, maybe faking an _etag query parameter.

Assaf

> Mike A
>
>
> On Jan 2, 2008 6:33 PM, Assaf Arkin <assaf@...> wrote:
> > To me, the use of XML is confusing, it leads to thinking of the
> > resource in terms of a closed, well-formed document, coloring the
> > decision.
> >
> > I think it's easier to start by talking about forms and URL-encoded
> > updates, with XML being an alternative encoding. For that, I can find
> > a lot of interesting examples in the wild. (Ignore the fact that
> > hForms uses POST for now, think HTML 5 and PUT)
> >
> > * I can create a form that will update all the values associated with
> > the resource, but also a form to update some of these values, or offer
> > both alternatives for the same resource. Is one better than the
> > other?
> >
> > * I can allow the form to mark which part of the resource gets
> > updated, much the same way printed forms have an optional 'change of
> > address' part with a checkbox.
> >
> > * I can pre-fill the form with existing values from the resource, and
> > just write over the resource from all the request parameters. But
> > sometimes, I would chose not to process missing values; account
> > setting pages use that when updating passwords, but ignoring empty
> > password fields.
> >
> > Which is acceptable and which would you frown upon?
> >
> >
> > -- Assaf
> > http://labnotes.org
> >
> >
> >
> >
>
> > Yahoo! Groups Links
> >
> >
> >
> >
>
>
>
> --
> mca
> "In a time of universal deceit, telling the truth becomes a
> revolutionary act. " (George Orwell)
>

I m a little confused. :) Is the resource update or shipping address or either depending on the situation? I do like where the discussion with Asaf went in

Message 6 of 7
, Jan 3, 2008

I'm a little confused. :)

Is the resource 'update' or 'shipping address' or either depending on
the situation?

I do like where the discussion with Asaf went in that the user
interface (driven by the server) should influence what updates are
truly safe. My experience, is that the forms displayed generally show
all properties of a resource.

Assaf Arkin

... Typically an account settings page will show you most if not all of the values associated with that resource (your account). But the form will only

> I'm a little confused. :)
>
> Is the resource 'update' or 'shipping address' or either depending on
> the situation?
>
> I do like where the discussion with Asaf went in that the user
> interface (driven by the server) should influence what updates are
> truly safe. My experience, is that the forms displayed generally show
> all properties of a resource.

Typically an account settings page will show you most if not all of
the values associated with that resource (your account). But the form
will only provide the fields you're able to update. Many services
will show your username and e-mail address, but the form only allows
for changing the e-mail address. Some prominently display the date
you joined the service (and effectively created the resource), but
won't let you edit that one either.