Resource Versioning

ETags

OCLC uses ETags (RFC2616) for handling caching and concurrency control of resources.

You may need to refer to a specific version of a particular entry. This is important in two cases in particular:

• Doing a "conditional retrieval," in which your client requests an entry, and the server sends the entry only if it has changed since the last time the client requested it.
• Ensuring that multiple clients do not inadvertently overwrite one another's changes. The Data APIs do this by making updates and deletes fail if the client specifies an old version identifier for the entry.

ETag Usage

The OCLC Web Services provide ETags in two places:

• ETag HTTP header
• gd:etag attribute of Atom <feed> and <entry> elements

Example - Header
ETag: "S0wCTlpIIip7ImA0X0QI"

Example - Feed
<feed xmlns='http://www.w3.org/2005/Atom'
   xmlns:gd="http://schemas.google.com/g/2005"
   gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>

Example - Entry
<entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>

An ETag is usually a string of letters and numbers, sometimes including hyphens and periods. The string is usually enclosed in quotation marks (the quotation marks are part of the ETag).

Strong vs Weak ETags

There are two kinds of ETags: strong and weak.

Strong ETags

• Strong ETags identify a specific version of a specific entry, and can be used to avoid overwriting other clients' changes.
• Strong ETags are used only for entries.

Weak ETags

• Weak ETags, in the context of the OCLC Data APIs, are used only for "conditional retrieval".
• Weak ETags always start with W/.
• ETags on feeds are always weak.

Example - Weak ETag
ETag: W/"D08FQn8-eil7ImA9WxZbFEw."