226

IM Used

2xx Success

Back to list.md

ELI5

Instead of sending the whole thing again, the server sent the changes needed to update what you already have.

Server perspective

Use 226 when the response body is not the full current representation, but the result of an agreed instance manipulation such as delta encoding.

When to use

  • •Return 226 only when the client explicitly negotiated a supported instance manipulation
  • •Use it for specialized caching or synchronization flows, not mainstream JSON APIs
  • •Delta encoding where the client already has an earlier representation
  • •Specialized HTTP clients that explicitly negotiate instance manipulations with A-IM
  • •Bandwidth-sensitive synchronization flows using standards-based delta responses

How to respond

  • •Use it for GET responses where the client negotiated A-IM and the server can describe the current representation with validators
  • •Document the manipulation algorithm and negotiation rules clearly
  • •Return an ETag for the current representation, and include Delta-Base when the client might need help identifying which prior representation the delta applies to
  • •Make sure validators and reconstruction rules let the client rebuild the intended current representation

Headers to consider

  • •A-IM
  • •If-None-Match
  • •IM
  • •Delta-Base
  • •ETag

Response body

  • •Return the manipulated or delta-encoded payload, not the plain full representation

Server-side pitfalls

  • •Do not use 226 when the client does not understand the negotiated manipulation
  • •Do not confuse 226 with byte ranges or application-level patch documents
  • •Ordinary APIs where clients do not support delta encodings
  • •Simple partial delivery, which is usually a 206 Partial Content case instead
  • •Generic patch or diff APIs that are not using HTTP instance-manipulation semantics

Examples

Delta-encoded document refresh

Request:GET https://api.example.test/doc # Headers A-IM: diffe If-None-Match: "doc-v1"
Response:226 IM Used # Headers Content-Type: application/json IM: diffe ETag: "doc-v2" Delta-Base: "doc-v1" # Body {"delta":"..."}

The client proves it already has an older representation, and the server returns a delta plus validators for the current one instead of resending the full document.

References

Related Status Codes

200

OK

Everything worked perfectly! The server understood your request and sent back exactly what you asked for.

206

Partial Content

You asked for just a piece of a file (like pages 5-10 of a book), and here's that specific piece you wanted!

304

Not Modified

You already have the latest version! The thing you're asking for hasn't changed since you last got it.