226 IM Used
HTTP response status code 226 IM Used is returned by the server to indicate that it has fulfilled a GET request that was sent with an A-IM header included, and the HTTP response is the result of one or more Instance Manipulations (IMs).
A HTTP response with status code 226 IM Used can be cached and used as part of a reply to subsequent HTTP requests. However, it is governed by the requirements of the expiration mechanism and Cache-Control HTTP headers. It can more freely be used in conjunction with a cache entry for the base instance to create a cache entry for the current instance.
Usage
When the 226 IM Used status code is received, the server has indicated that the instance is a modified version of the actual resource. One example of usage is delta encoding, which can be employed to conserve bandwidth in cases where only a portion of a resource has changed. Rather than send the entire resource in the message body, particularly if something quite similar is already in the cache, it may support only sending the differences, or delta, and rely on the client to assemble it.
The types of instance manipulations applied will be those from which the client has indicated it supports. The Accepted Instance Manipulations (A-IM) can be specified in the request on either a single line, comma-delimited, or on multiple lines.
It is important to consider that the unmodified current instance may not be available. Recreating it may be possible by combining this HTTP response with previous or future HTTP responses, depending on which instance manipulations were applied.
Example
In the example, the client starts with an empty cache and requests a PDF file from the server. The client informs using the Accept-Encoding HTTP header that it also supports gzip Compression. In the initial HTTP response from the server, the client receives the gzip-encoded PDF file and a 200 OK response status code.
In the subsequent HTTP request, the client checks to see if the document has changed since the original HTTP request, which is done using the Etag and If-None-Match HTTP headers. Furthermore, the client indicates that it is willing to accept a delta file that is created using the VCDIFFF algorithm by specifying it in the A-IM HTTP header, and as before, gzip encoding is supported.
Based on the Etag HTTP header, the server recognizes that the document has changed and generates the delta file. Had the file not changed, the server may have returned a 304 Not Modified status code. For this example, the server’s method of generating the result in the message body is inconsequential, although it is noteworthy that there may be several approaches that it can follow, depending on the type of file and the encoding, and the efficiency of doing so may vary.
Ultimately, the client receives the delta file and can use it to create the updated version of the PDF document. To ensure that the client is using the correct base file, the Delta-Base HTTP header indicates which resource the server used. Also, the instance manipulations that were applied are specified in the A-IM HTTP header.
Initial request for document
GET /livingdocs/current_specs.pdf HTTP/1.1
Host: www.example.re
Accept-Encoding: gzip
Initial response from server
HTTP/1.1 200 OK
Etag: “1234 … 000"
Content-Encoding: gzip
<gzip-compressed file included in message body>
Next request for document
GET /livingdocs/current_specs.pdf HTTP/1.1
Host: www.example.re
If-none-match: “1234 … 000"
Accept-Encoding: gzip
A-IM: vcdiff
Next response from server
HTTP/1.1 226 IM Used
Etag: “1234 … 111"
Delta-base: “1234 … 000"
Content-Encoding: gzip
IM: vcdiff
<gzip-compressed delta file included in message body>
Code references
.NET
HttpStatusCode.IMUsed
Rust
http::StatusCode::IM_USED
Rails
:im_used
Go
http.StatusIMUsed
Symfony
Response::HTTP_IM_USED
Python3.5+
http.HTTPStatus.IM_USED
Apache HttpComponents Core
org.apache.hc.core5.http.HttpStatus.SC_IM_USED
Angular
@angular/common/http/HttpStatusCode.ImUsed
Takeaway
HTTP response status code 226 IM Used indicates that a HTTP request has been successfully completed, but the message body contains an instance that has been manipulated. In bandwidth-conserving situations where the message body contains a delta file, the client is responsible for recreating the actual instance using the cache.