Documentation

Rationale

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).

The Poem

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.

Edit Properties

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.
    

Effects on caching

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).

Acknowledgements

Thanks to Jan Algermissen for showing me Roy Fielding's email post on the subject.

References

  1. Hypertext Transfer Protocol -- HTTP/1.1
  2. Roy T. Fielding
  3. WebDAV vs HTTP method semantics
  4. Image maps
  5. Encoding Dublin Core Metadata in HTML (RFC2731)
  6. Dublin Core Metadata