Edit this page

API Server protocol
module up.protocol

Unpoly has an optional protocol your server may implement to exchange additional information when Unpoly is updating fragments. The protocol mostly works by adding additional HTTP headers (like X-Up-Target) to requests and responses.

Important

While the protocol can help you optimize performance and handle some edge cases, implementing it is entirely optional. For instance, unpoly.com itself is a static site that uses Unpoly on the frontend and doesn't even have an active server component.

Existing implementations

You should be able to implement the protocol in a very short time.

There are existing implementations for various web frameworks:

Topics

All features

HTTP
ETag stable

This response header contains a hash identifying the content in the response body.

HTTP
If-Modified-Since stable

This request header contains the last modification time of a fragment that is being reloaded.

HTTP
If-None-Match stable

This request header contains the ETag of a fragment that is being reloaded.

HTTP
Last-Modified stable

This response header contains the time when the content in the response body was last modified.

HTTP
_up_method stable

The server may set this optional cookie to echo the HTTP method of the initial request.

JS
up.protocol.config stable

Configures strings used in the optional server protocol.

HTTP
Vary stable

Request headers that influenced a response should be listed in a Vary response header.

HTTP
X-Up-Accept-Layer stable

The server may set this response header to accept the targeted overlay in response to a fragment update.

HTTP
X-Up-Clear-Cache deprecated

The server may send this optional response header to control which previously cached responses should be expired after this response.

HTTP
X-Up-Context experimental

This request header contains the targeted layer's context, serialized as JSON.

HTTP
X-Up-Dismiss-Layer stable

The server may set this response header to dismiss the targeted overlay in response to a fragment update.

HTTP
X-Up-Events stable

The server may set this response header to emit events with the requested fragment update.

HTTP
X-Up-Evict-Cache stable

The server may send this optional response header to control which previously cached responses should be evicted after this response.

HTTP
X-Up-Expire-Cache stable

The server may send this optional response header to control which previously cached responses should be expired after this response.

HTTP
X-Up-Fail-Context experimental

This request header contains the context of the layer targeted for a failed fragment update, serialized as JSON.

HTTP
X-Up-Fail-Mode stable

This request header contains the mode of the layer targeted for a failed fragment update.

HTTP
X-Up-Fail-Target stable

This request header contains the target selector for a failed fragment update.

HTTP
X-Up-Location stable

The server may set this response header to set a custom browser location after a fragment update.

HTTP
X-Up-Method stable

The server may set this optional response header to change the HTTP method after a fragment update.

HTTP
X-Up-Mode stable

This request header contains the targeted layer's mode.

HTTP
X-Up-Reload-From-Time deprecated

This request header contains a timestamp of an existing fragment that is being reloaded.

HTTP
X-Up-Target stable

This request header contains the target selector for a successful fragment update.

HTTP
X-Up-Title stable

The server may set this optional response header to change the document title after a fragment update.

HTTP
X-Up-Validate stable

This request header contains the names of the form fields being validated.

HTTP
X-Up-Version stable

This request header contains the current Unpoly version to mark this request as a fragment update.