226 IM Used

HTTP response status code 226 IM Used indicates the server fulfilled a GET request containing an A-IM header, and the response body is the result of one or more instance manipulations applied to the current instance of the resource.

Table of Contents

Usage
Example
Code references
Takeaway
See also

Usage

A 226 IM Used response tells the client the body contains a modified version of the resource rather than the full representation. One common use is delta encoding, where only the differences between the cached version and the current version are transmitted, conserving bandwidth.

The server applies the instance manipulations the client declared support for via the A-IM request header. Accepted manipulations are listed on a single comma-delimited line or across multiple lines.

Caching

A 226 IM Used response follows the delta caching rules defined in its own specification, not the standard heuristic caching list. The response is usable alongside a cached base instance to construct a cache entry for the current instance, and standard Cache-Control directives still apply when present.

The unmodified current instance is not always available directly. Reconstructing the full resource requires combining the 226 response with a previously cached base instance, guided by the instance manipulations the server applied.

Example

The client starts with an empty cache and requests a PDF file. The Accept-Encoding header signals support for gzip Compression. The server responds with the full gzip-encoded file and a 200 status.

On the next request, the client checks whether the document changed by sending the ETag value from the first response in an If-None-Match header. The client also declares support for vcdiff delta encoding via the A-IM header.

The server detects the resource changed since the original ETag and generates a delta file. An unchanged resource produces a 304 instead. The Delta-Base header in the response identifies which cached version the delta is computed against. The IM header lists the instance manipulations applied.

Request

GET /livingdocs/current_specs.pdf HTTP/1.1
Host: www.example.re
Accept-Encoding: gzip

Response

HTTP/1.1 200 OK
ETag: "1234-000"
Content-Encoding: gzip

<gzip-compressed file>

Request (subsequent)

GET /livingdocs/current_specs.pdf HTTP/1.1
Host: www.example.re
If-None-Match: "1234-000"
Accept-Encoding: gzip
A-IM: vcdiff

Response (delta)

HTTP/1.1 226 IM Used
ETag: "1234-111"
Delta-Base: "1234-000"
Content-Encoding: gzip
IM: vcdiff

<gzip-compressed delta file>

Code references

.NET

HttpStatusCode.IMUsed

Rust

http::StatusCode::IM_USED

Rails

:im_used

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 confirms the server applied one or more instance manipulations to produce the response body. In delta encoding scenarios, the client reconstructs the full resource by combining the delta with a cached base instance.