“If-Modified-Since” HTTP Request Header

Entity HEAD requests allow for the requester to optionally pass the “If-Modified-Since” HTTP header in the request. This is only permitted for retrieve style requests when querying for a specific resource by id in the URL. The header’s value is the target date-time in iso-8601 format in the appropriate time zone. When provided, the value will be compared to the resource’s last modification time to determine if it has been modified since the header’s date-time. If the resource exists, and it has been modified, a 200 - Ok status code is returned. If it exists but has not been modified, a 304 – Not Modified status code is returned.

Not that if the entity does not support mod time tracking, the header is ignored and a 200 – Ok response code is returned meaning only that the resource exists.

The “If-Modified-Since” request header is typically used in conjunction with the “Last-Modified” response header that is returned with every retrieve style GET request for those entities that track mod timestamps. For example, a common scenario might start with a retrieve style GET request being made for a resource. The value of the “Last-Modified” response header is saved client-side for that resource. Sometime later, the client wants to check if the resource has been updated. A HEAD request can be made to determine if the resource has been modified since the original GET request by passing the last mod timestamp in the “If-Modified-Since” request header.

In scenarios where the updated resource representation is not needed, a HEAD request is much more efficient than a GET request. Or, it may be used to determine if a more expensive GET request is subsequently called to fetch the updated resource representation. It is also common to use HEAD request modification checks as a trigger mechanism for down-steam operations.