UIAP HTTP/REST Binding

UIAP HTTP/REST Binding v0.1

Field	Value
Status	Draft
Version	0.1
Date	2026-03-27
Dependencies	[UIAP-CORE]
Editors	Patrick

1. Purpose

This document defines an optional, intentionally constrained HTTP/REST Binding for UIAP.

The binding is suitable for request/response-dominated integrations but is not the primary reference binding for highly event-driven, interactive UIAP runtimes.

---

2. Identifier

type BindingId = "http@0.1";
const UIAP_HTTP_MEDIA_TYPE = "application/uiap+json";

---

3. Classification

http@0.1 is a conservative supplementary binding.

It is suitable for:

• controlled backend integrations,
• desktop or local host setups,
• deployments where WebSocket is organizationally or infrastructurally undesirable,
• simple controller-to-runtime communication.

It is less suitable for dense event streams such as:

• action.progress
• uiap.workflow.progress
• web.state.delta
• web.signal
• aggressive heartbeat usage

For such cases, ws@0.1 SHOULD be preferred.

---

4. Recommended Resource Model

interface HTTPBindingConfig {
  baseUrl: string;

  sessionPath?: string;              // default RECOMMENDED: "/uiap/sessions"
  messagePathTemplate?: string;      // default RECOMMENDED: "/uiap/sessions/{sessionId}/messages"
  eventStreamPathTemplate?: string;  // default RECOMMENDED: "/uiap/sessions/{sessionId}/events"

  eventDelivery?: "sse";             // v0.1 RECOMMENDED and effectively normative
  reconnect?: ReconnectPolicy;
}

Rules

1. The concrete URI structure is deployment-specific but MUST be documented.
2. The model shown above is RECOMMENDED.
3. New sessions SHOULD be created via POST {sessionPath} with a session.initialize envelope.
4. Active sessions SHOULD be addressed via POST {messagePathTemplate}.
5. Server-initiated events SHOULD be delivered via GET {eventStreamPathTemplate} as Server-Sent Events (SSE).

---

5. Connection Establishment and Teardown

Establishment

1. The client sends session.initialize via HTTP POST.
2. The server responds with exactly one UIAP envelope, typically session.initialized or error.
3. After successful initialization, the client SHOULD open the session’s event stream.
4. After that, further UIAP requests MAY be sent via the message endpoint.

Teardown

1. An orderly session termination SHOULD be performed via session.terminate.
2. A server MAY additionally offer DELETE /uiap/sessions/{sessionId}, but MUST internally map this to session.terminate semantics.
3. Simply closing an individual HTTP connection does not automatically terminate the UIAP session.

---

6. Framing

6.1 Request/Response Channel

1. An HTTP request body MUST contain exactly one UIAP envelope.
2. An HTTP response body MUST contain exactly one UIAP envelope.
3. The media type SHOULD be application/uiap+json.
4. If this media type is not practicable, application/json MAY be used, as long as exactly one UIAP envelope is in the body.
5. Multiple UIAP envelopes in a single HTTP body are non-conformant.
6. An empty 202/204 response without a UIAP envelope is not interoperable enough for general UIAP requests and SHOULD be avoided.

6.2 SSE Event Channel

1. Each SSE event MUST contain exactly one UIAP envelope.
2. The event field SHOULD be uiap.
3. The data: content MUST be a JSON-serialized UIAP envelope.
4. The id: field SHOULD carry a monotonic stream cursor or event identifier so that reconnect is traceable.
5. action.progress, action.result, uiap.workflow.progress, web.state.delta, web.signal and similar server-initiated messages SHOULD be sent via this channel.

Example: SSE

event: uiap
id: ev_1042
data: {"uiap":"0.1","kind":"event","type":"action.progress","id":"msg_79","sessionId":"sess_123","ts":"2026-03-27T10:03:00.020Z","source":{"role":"bridge","id":"http-runtime"},"payload":{"actionHandle":"act_991","stage":"executing"}}

---

7. Error Handling

1. HTTP errors before successful UIAP processing — such as auth errors, unknown endpoint, incorrect content type, body too large or unparseable JSON — are transport errors.
2. Once a request has been accepted as a valid UIAP envelope, the business or protocol-level response SHOULD be delivered as a UIAP response or UIAP error in the body.
3. HTTP status codes SHOULD primarily express transport, gateway and preprocessing errors.
4. UIAP error codes such as invalid_message, bad_request, unknown_session, session_not_active or permission_denied belong in the UIAP error envelope.
5. If the SSE stream breaks, that is initially a transport problem of the event channel, not automatically the end of the session.

---

8. Security Requirements

1. https:// SHOULD be the default.
2. Plain http:// MAY only be used for loopback, local development or equivalently protected internal environments.
3. Authentication MUST be governed per deployment, for example via bearer token, cookies or mTLS.
4. When browser clients work with cookies, CORS and CSRF protection mechanisms SHOULD be explicitly considered.
5. resumeToken MUST NOT be transported in URL paths, query strings or SSE cursors.
6. Event streams MUST only be accessible to authorized session participants.

---

9. Reconnect and Session Resume

1. The loss of an individual HTTP connection does not automatically mean session loss.
2. If only the SSE stream drops, the client SHOULD reopen it with the same sessionId and the last known event cursor.
3. If the server signals that the stream cursor is no longer resumable or the session is no longer active, the client SHOULD send session.resume via the message endpoint.
4. If session.resume fails, a new session MUST be started with session.initialize.
5. In-flight requests with unknown delivery or execution status MUST NOT be blindly retried automatically.

---

10. Minimal Flow

POST /uiap/sessions
Body = session.initialize
<- session.initialized

GET /uiap/sessions/sess_123/events
<- SSE stream with action.progress / web.state.delta / workflow.progress

POST /uiap/sessions/sess_123/messages
Body = action.request
<- action.accepted

... further progress/result/signal messages via SSE ...

---

11. A Clear Design Decision

A “REST binding” for UIAP only works cleanly when one honestly acknowledges that UIAP is not merely composed of static CRUD operations. Session lifecycle, progress events, deltas, resume and heartbeats require at least a supplementary event channel. That is why http@0.1 in this form is HTTP request/response plus SSE, not romanticized JSON-POST folklore.

---

Normative Keywords

The key words MUST, MUST NOT, SHOULD, MAY in this document are to be interpreted as described in RFC 2119 and BCP 14, when and only when they appear in ALL CAPS.

---

Normative References

• [UIAP-CORE] UIAP Core v0.1
• [RFC2119] Key words for use in RFCs to Indicate Requirement Levels, BCP 14
• [RFC7231] Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
• [W3C-SSE] Server-Sent Events, W3C Recommendation

Security Considerations

• HTTPS SHOULD be used for all production deployments.
• Authentication MUST be governed per deployment (bearer token, cookies, mTLS).
• resumeToken MUST NOT be transported in URLs or query strings.
• SSE event streams MUST only be accessible to authorized session participants.
• CORS and CSRF protection mechanisms SHOULD be explicitly configured for browser clients.

Changelog

Version	Date	Changes
0.1	2026-03-27	Initial draft