PUT - Loading a Screen

---

At a Glance

• PUT loads one full screen definition.
• The response defines layout, elements, and update rules.
• elements defines the initial UI.
• patches defines incremental updates.
• timeout sets the next update cycle.
• update defines the PATCH endpoint.

Purpose

The PUT method enables the client to load a screen. When you call the endpoint for a screen, the server returns a JSON object that defines layout, widgets, and update rules for the page and initialize update logic. This operation remains stateless. Each call supplies a complete definition for the screen and does not depend on previous calls.

Response Structure

A successful call returns a 200 HTTP status and includes a single JSON object with the fields below.

Screen Properties

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

Field	Type	Description
title	string	Human-readable page title for the browser tab or header bar.
type	string	Defines the layout category. Accepted values: Page (full-width layout), Column (narrow layout), Popup (dialog window), Cover (full-screen modal), Video (view for doctor–patient video calls).
blocking	boolean	For Popup and Cover types, indicates whether the modal includes a close button. This value is ignored for other types.
locale	string	Locale code such as en-gb for language and regional formatting.
font-version	string	Icon font version. If the client caches a different version, the client must download and cache an update.
url	string	Suggested URL suffix for the opened screen. Suitable for client-side routing or shareable links.
elements	array	Ordered list of objects that define the UI components on the screen such as widgets, their properties, and their behaviors. Refer to the Screen Composition (coming soon) section for details.
patches	object	Map of object references to updates that apply to the screen. Each key is the identifier of an element or container. The corresponding value is either (1) an object with fields that update that element or (2) an array that replaces a list of objects. The server never changes element type through PATCH. To delete an element, replace its entry with an empty array. The patches property also applies when you open a page that is a popup and the same operation updates elements on the parent page.
update	string	PATCH endpoint for updates to this screen such as incremental updates.
timeout	number	Number of seconds that the client waits before the client calls the endpoint in update to obtain incremental changes.

Handling Patches and Timeouts

After the client renders the initial page from the elements array, the client starts a timer using the timeout value. When the timer expires, the client calls the PATCH endpoint in the update field to receive incremental updates. The client applies any returned patches to the existing UI.

A PATCH response can include a timeout value that starts the next update cycle.

Update Sequence

1. Render the UI from elements.
2. Start the timeout countdown.
3. Call the update endpoint.
4. Apply returned patches.
5. Repeat the cycle when a new timeout value appears.

Popup and Cover Behaviors

Popup and Cover types act as modal overlays. The blocking value defines manual close control. If blocking is true, omit the close button and rely on server‑driven flows to dismiss the modal. If blocking is false, include a close button that the client uses to close the modal without server-driven dismissal.

Value	Close Button	Behavior
blocking = true	No	Server controls dismissal
blocking = false	Yes	Client closes modal

Video Pages

When type is Video, the client configures a dedicated layout for live video calls. The elements array includes widgets for camera and microphone controls. The PATCH endpoint updates call status, participants, and messages.

A video page is unique in the application because the Air Doctor server does not define the entire structure. Some components remain hardcoded client-side elements. Refer to the Screen Composition (coming soon) for Video pages.

Next Steps

• Use the PUT endpoint to load the screen.
• Use the update endpoint to apply incremental updates.
• Review the PATCH documentation for update formats.
• Refer to Screen Composition (coming soon) for widget definitions and layout structure.