This page demonstrates an HTTP[1] resource update
pattern based on an idea by Roy Fielding[2].
At the end of a post on the topic of WebDAV semantics[3],
Fielding illustrates one way to expose and manipulate a set of properties for a resource using
a URI convention (similar to that used for HTML image maps[4])
where appending ;props to a resource URI allows clients to access
any available properties for that resource.
Since I first saw this idea articluated by Fielding, I've dubbed the pattern Fielding Property Maps (without
his knowledge or consent).
This example uses a short poem that appears in RFC2731[5]
to illustrate encoding Dublin Core Metadata[6] into HTML documents.
The document can be loaded using a common browser and, in 'view source' mode, users can see
the meta tags in the head section of the document that contain
the Dublin Core Metadata values.
The "Edit Properties" resource can be used to modify the metadata for the poem document using the Fielding Property Maps pattern. It supports the following:
GET /poem;props retrieves a list of properties for that document
GET /poem;props?{dcterm} retrieves a single property for that document
PUT /poem;props?{dcterm} supports updating the value the indicated property
DELETE /poem;props?{dcterm} deletes the value for the indicated {dcterm},
but does not remove the actual metadata entry.
When this pattern is used to modify public
properties associated with the resource (e.g. Dublin Core values published as meta
elements in the head section of the HTML document used in the Poem example)
then the pattern is, essentially, acting as a partial update for the associated resource.
As with any partial update pattern, Fielding Property Maps
can have negative effects on HTTP caches.
In the case of each property edit (e.g. /poem;props?author)
shared and private caches should have no problem maintaining a fresh copy of the
property resource.
However, the cached primary resource (e.g. /poem) can become 'stale' since
caches are not likely to flush their copy when the associated property is modified.
This problem
can be mitigated by using 1) a Cache-Control header that contains
Last-Modified and/or ETag values on the primary resource; or 2)
setting the primary resource Cache-Control header to
No-Cache.
These less-than-optimal solutions may not be needed in cases where the property values
are non-critical to the operation of the resource (most meta tags in the
head section of HTML documents fall into this category) or
when this pattern is used to update properties
of a resource that are not published within the primary resource (e.g. ?lock
or other similar values).
Thanks to Jan Algermissen for showing me Roy Fielding's email post on the subject.