Conditionally retrieving an object
You can choose to retrieve an object only if its ETag and/or last modification date and time meet certain criteria. You might do this, for example, in an application that maintains a local cache of frequently used objects. With such an application, you can reduce the load on HCP and the network by retrieving objects only if they have changed in some way since they were cached.
You use the If-Match
, If-None-Match
, If-Modified-Since
, and If-Unmodified-Since
request headers to make GET request conditional:
- The
If-Match
andIf-None-Match
headers compare the ETag for the requested object to one or more values that you specify. Typically, each value is the ETag for an object of interest. - The
If-Modified-Since
andIf-Unmodified-Since
headers compare the date and time the requested object was last modified to a date and time that you specify.
If the requested object meets all the conditions specified by the conditional headers included in the request, HCP returns the object data. If the specified item does not meet the condition specified by:
- An
If-Match
orIf-Unmodified-Since
header, HCP returns a 412 (Precondition Failed) status code and does not return the object data - An
If-None-Match
orIf-Modified-Since
header, HCP returns a 304 (Not Modified) status code and does not return the object data
If a request includes multiple different conditional headers, HCP processes any If-Match
and If-None-Match
headers before any If-Modified-Since
or If-Unmodified-Since
headers. If a request includes more than one of any given header, HCP processes only the first one of those headers and ignores the others.