X-Up-Context - Unpoly

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

Example

The current layer has a context { lives: 3 }. When the user updates a fragment, Unpoly automatically includes the following request headers:

X-Up-Context: { "lives": 3 }
X-Up-Target: main

The server may choose to render HTML based on that context, e.g. by including a live counter in the response. It responds with the following HTTP:

Vary: X-Up-Context

<main>
  3 lives left
  ...
</main>

Note

Request headers that influenced a response should be listed in a Vary response header. This tells Unpoly to partition its cache for that URL so that each request header value gets a separate cache entries.

Updating context from the server

The server may update the layer context by sending a X-Up-Context response header with changed key/value pairs:

Content-Type: text/html
X-Up-Context: { "lives": 2 }

<html>
  ...
</html>

Important

HTTP headers may only contain US-ASCII (7-bit) characters. If you have higher code points in a JSON value, you may encode those characters using Unicode escape sequences.

Upon seeing the response header, Unpoly will merge the server-provided context object into the layer's context object, adding or replacing keys as needed. Client-side context keys not mentioned in the response will remain unchanged.

There is no explicit protocol to remove keys from the context, but the server may send a key with a null value to effectively remove a key.

The frontend will use the server-provided context upates for both successful (HTTP status 200 OK) and failed (status 4xx or 5xx) responses. If no X-Up-Context response header is set, the updating layer's context will not be changed.

It is recommended that the server only places changed key/value pairs into the X-Up-Context response header, and not echo the entire context object. Otherwise any client-side changes made while the request was in flight will get overridden by the server-provided context.

up.protocol X-Up-Context HTTP header

Example

Note

Updating context from the server

Important

up.protocol X-Up-Context
HTTP header