HTTP conditional requests

HTTP has a concept of conditional requests, where the result, and even the success, of a request can be changed by comparing the affected resources with the value of a validator. Such requests can be useful to validate the content of a cache, and sparing a useless control, to verify the integrity of a document, like when resuming a download, or when preventing to lose updates when uploading or modifying a document on the server.

Principles

HTTP conditional requests are requests that are executed differently depending on the value of specific headers. These headers define a precondition and the result of the request will be different if the precondition is matched or not.

The different behaviors are defined by the method of the request used and by the set of headers used for a precondition:

• for safe methods, like GET, which usually tries to fetch a document, the conditional request can be used to send back the document if relevant only and therefore spares bandwidth.
• for unsafe methods, like PUT, which usually uploads a document, the conditional request can be used to upload the document only if the original it is based on is the same that is stored on the server.

Validators

All conditional headers try to check if the resource stored on the server matches a specific version. To achieve this, the conditional requests need to indicate the version of the resource. As comparing the whole resource byte to byte is impracticable (and not even always what is wanted!), the request transmits a value describing the version: such values are called validators and are of two kinds:

• the date of last modification of the document, the last-modified date.
• an opaque string, uniquely identifying each version, called the entity tag or the etag.

Comparing versions of the same resource is a bit tricky: depending of the context, there are two kind of equality checks. Strong validation is used when byte to byte identity is expected, for example when resuming a download. Weak validation is used when the user-agent only needs to determine if the two resources have the same content, even if they are minor difference (like different ads, or a footer with a different date).

The kind of validation is independent of the validator used; both Last-Modified and ETag allow both types of validation though the complexity to implement it on the server side may vary. HTTP uses strong validation by default, and it specifies when weak validation can be used.

Strong validation

Strong validation consists in guaranteeing that the resource is byte to byte identical to the one it is compared too. This is mandatory for some conditional headers, and the default for the others. Strong validation is very strict and may be difficult to guarantee at the server level, but it does guarantes no data loss at any time, sometimes at the expense of performance.

It is quite difficult to have a unique identifier for strong validation with Last-Modified. Often this is done using an ETag with the MD5 hash of the resource (or a derivative).

Weak validation

Weak validation differs from strong validation as it considers two versions of the document as identical if the content is equivalent. For example, a page that would differ from another only by a different date in its footer, or by different advertisement, would be considered as identical to the other with weak validation, but will be considered as different with strong validation. Building a system of etags that creates weak validation may be complex as it involves knowing the importance of the different elements of a page, but is very useful to optimize caching performance.

Conditional headers

Several HTTP headers, called conditional headers, lead to conditional requests. These are:

If-Match

Succeeds if the ETag of the distant resource is equal to one listed in this header. By default, unless the etag is prefixed with 'W/', it performs a strong validation.

If-None-Match

Succeeds if the ETag of the distant resource is different to each listed in this header. By default, unless the etag is prefixed with 'W/', it performs a strong validation.

If-Modified-Since

Succeeds if the Last-Modified date of the distant resource is more recent than the one given in this header.

If-Unmodified-Since

Succeeds if the Last-Modified date of the distant resource is older or the same than the one given in this header.

If-Range

Similar to If-Match, or If-Unmodified-Since, but can have only one single etag, or one date. If it fails, a the range request fails and, instead of a 206 Partial Content response, a 200 OK is sent with the complete resource.

Use cases

Cache update

The most common use case for conditional requests is updating a cache. With an empty cache, or without a cache, the requested resources is sent back with a status of 200 OK.

Together with the resource, the validators are sent in the headers. In this example, both Last-Modified and ETag are sent, but it could have been only one of them as well. These validators are cached with the resource (like all headers) and will be used to craft conditional requests once the cache becomes stale.

As long as the cache is not stale, no requests are issued at all. But once, it has become stale, this is mostly controlled by the Cache-Control header, the client doesn't use the cached value directly but issues a conditional request, with the value of the validator used as parameter of the If-Modified-Since and If-Match headers.

If the resource has not been changed, the server sends back a 304 Not Modified response, which makes the cache fresh again and the client use the cached resource. Although there is a response/request round-trip that consumes some resources, this is more efficient than to transmit the whole resource over the wire again.

If the resource has changed, the server just sends back a 200 OK response, with the new version of the resource, like if the request wasn't conditional and the client use this new resource (and caches it).

Besides setting the validators on the server side, this mechanism is transparent: all browsers manage a cache and send such conditional requests without any special work to be done by Web developers.

Integrity of a partial download

Partial downloading of files is a functionality of HTTP that allows to resume previous operations, saving bandwidth and time by keeping the already obtained information.

A server supporting partial downloads advertised it by sending the Accept-Ranges header. When this happens, the client can resume a download by sending a Ranges header with the missing ranges.

The principle is simple, but there is one potential problem: if the downloaded resource has been modified in-between the two downloads, the obtained ranges will correspond to two different versions of the resource and the final document will be corrupted.

To prevent this, conditional requests are used. For ranges, they are two ways of doing this. The more flexible one makes use of If-Modified-Since and If-Match and the server returns an error if the precondition fails; the client then restarts the download from the beginning.

Even if this method works, it adds an extra response/request exchange when the document has been changed. This impairs the performance and HTTP has an extra specific header to avoid this: If-Range.

This solution is more efficient, but slightly less flexible (only one etag can be used in the condition), though this added flexibility is rarely needed.

Avoiding the lost update problem with optimistic locking

A common operation in Web applications is to update a remote document. This is very common in any file system or source control applications, but any application that allows to store remote resources needs such a mechanism. Similarly, common Web sites like wikis and other CMS have such a need.

With the PUT method you are able to implement this. The client first reads the original files, modifies them and finally pushes them to the server.

Unfortunately, things get a little bit awry as soon as we take into account concurrency. While a client is modifying locally its new copy of the resource, a second client can fetch the same resource and do the same on its side. What happens then is very unfortunate: when they commit back, the modifications of the first client to push are discarded by the next push, as the second client is unaware of the new changes. The decision about who wins is not communicated to the other party, but which client's changes will be kept will vary with the speed they commit, which depends on the performance of the clients, of the server, and even of the human editing the document at the client: the winner will change from one time to another. This is a race condition and leads to problematic behaviors difficult to detect and to debug.

There is no way in dealing with this problem without annoying one of the two clients. But lost updates and race conditions are to be avoided: we want a predictable results and that the clients are notified when their changes are rejected.

Conditional requests allow to implement the optimistic locking algorithm (used by most wikis or source control systems). The idea is to allow all clients to get copies of the resource, to let them modify it locally and to control concurrency by allowing the first client submitting an update to do it successfully, all subsequent updates based on the now obsolete version of the resource are rejected.

This is implemented using the If-Match or If-Unmodified-Since headers. If the etag doesn't match the original file, or if the file has been modified since it has been obtained, the change is simply rejected with a 412 Precondition Failed error. It is up to the client to then deal with the error, either by notifying the human behind to start again, this time on the newest version, or by helping the person by showing them a "diff" and letting the human choose the changes to keep.

Dealing with the first upload of a resource

The first upload of a resource is an edge case of the previous: like for any update of a resource, it is subject to a race condition if two clients try to perform it at the same time (or almost). To prevent this, conditional requests can be used: by adding If-None-Match with the special value of '*', representing any etag, the request will succeed only if the resource didn't exist before.

If-None-Match will work only with HTTP/1.1-compliant server (and later). If you don't know if the server will be compliant, you need first to issue a HEAD request to the resource to check it.

Conclusion

Conditional requests are a key feature of HTTP and allow to build efficient and complex applications. For caching, or resuming downloads, the only work requested to webmasters is to configure the server correctly (setting up correct etags in some environment can be tricky), and Web developers have nothing to do as the browser will serve the right conditional requests.

For locking mechanisms, it is the opposite, Web developers need to issue request with the proper headers, while webmasters can rely on the application most of the time to make the check for them.

In both cases, conditional requests are a fundamental feature of the Web.