PATCH - Updating a Screen

---

At a Glance

• PATCH reports user actions and state changes.
• The server evaluates the new state and prepares incremental updates.
• patches defines updates for existing elements.
• update defines the next PATCH endpoint.
• timeout sets the next update cycle.
• PATCH does not redefine the screen layout.

The PATCH method supports three roles. The roles define how your client reports user activity, permissions, location, and timed updates to the server.

Role 1: PATCH reports the user action acknowledgment and sends current screen state

When the user selects an option or clicks a button, your client calls the PATCH endpoint when the screen design specifies a call for that control. This call notifies the server of the event and sends the current state of all on-screen fields. The server evaluates the state and determines whether the screen requires an update.

Role 2: PATCH reports permissions and location updates

When the user grants or revokes access to the camera, microphone, or GPS, or when the client receives new coordinates, your client calls the patch endpoint. This call informs the server of the changed permissions or location. Include the X-Camera, X-Microphone, X-Location, and X-Coordinates headers with their current values.

Role 3: PATCH checks for updates after the timeout, periodic refresh

The timeout value in the PUT response or previous PATCH response instructs your client on the number of seconds to wait before it checks for new data. When the timer ends, your client calls the PATCH endpoint to request incremental changes. When the response omits a timeout value, the client does not set a timer. Additional PATCH calls trigger only after user actions or permission or location changes.

PATCH Lifecycle Overview**

[Trigger: User action or state change]
      ↓
[PATCH Request]
      ↓
[Server evaluates state]
      ↓
[Incremental Updates in `patches`]
      ↓
[Client applies updates]
      ↓
[Start a timeout when the field exists]
      ↓
[Next PATCH call]

PATCH Request

Send a PATCH request to the appropriate endpoint. The request includes:

• All current field values – Pass the current values of every input field in the model, including fields on the screen and fields that remain hidden. Include all fields even when only one value changes. This approach ensures the server receives a complete snapshot of the user state.
• All appropriate headers – When applicable, include the X‑Camera, X‑Microphone, X‑Location, X‑Coordinates, and any other required headers. These headers reflect the current permission status and the current position of the device.
• File field indicators – For file attachments, do not send file data in a PATCH call. Supply a boolean for single‑file fields (true when a file exists, false when no file exists) and an integer for multi‑file fields that indicates how many files the user attaches. The POST operation handles the actual upload.

The server uses this information to process the user action or state change and prepare a set of patches.

Response Structure

A successful call returns a 200 HTTP status and a JSON object that mirrors the structure of the PUT response but omits values that stay constant.

Navigation and Metadata Fields

PATCH Response Fields

The table defines each field, its type, and its description.

Field	Type	Description
title	string	Updates the page title when context changes.
url	string	Suggested URL suffix for the current page state. This value updates when the user moves to a new logical step.
update	string	Endpoint for the next PATCH call. The value stays the same or change based on navigation.
timeout	number	Number of seconds the client waits before the next call through the endpoint in update. This value controls the poll cycle.

PATCH Content Fields

Field	Type	Description
patches	object	Map of updates for elements on the screen. Each key identifies an element or container. Each value contains new properties or a replacement array.

Values from the PUT response such as type, blocking, locale, and elements do not repeat in a PATCH response because these values stay constant during the active screen session.

PATCH Application

When your client receives a PATCH response:

1. Update title and URL – When title or url fields appear and differ from the current values, update the client output such as change the document title or browser history.
2. Apply patches – Iterate through the patches object and apply updates to the correct element. Merge updated properties into the existing element. Replace arrays with new arrays. Remove elements when the value is an empty array.
3. Schedule updates – When the response contains a timeout value, start a timer for the specified number of seconds and call the endpoint in update after that period. When the response omits timeout, do not start an automatic call. The next PATCH call occurs only after direct user actions.

PATCH Application Sequence

[Response arrives]
      ↓
[Check `title` and `url`]
      ↓
[Process each entry in `patches`]
      ↓
[Merge or replace element data]
      ↓
[Remove the element when the value is an empty array (`[]`)]
      ↓
[Check `timeout`]
      ↓
[Start a timer or wait for the next user action]

Summary

Use the PATCH endpoint to inform the server of user actions and to obtain incremental changes to the current screen. The response updates existing elements and does not redefine the entire page. Use the timeout value to control the poll cycle and handle each PATCH without delay so the user interface stays in sync with server state with minimal overhead.