UIAP HTTP/REST Binding

UIAP HTTP/REST Binding v0.1

Feld	Wert
Status	Draft
Version	0.1
Datum	2026-03-27
Abhängigkeiten	[UIAP-CORE]
Editoren	Patrick

1. Zweck

Dieses Dokument definiert ein optionales, bewusst eingeschränktes HTTP/REST Binding für UIAP.

Das Binding ist für request/response-dominierte Integrationen geeignet, ist aber nicht das primäre Referenzbinding für stark event-getriebene, interaktive UIAP-Laufzeiten.

---

2. Kennung

type BindingId = "[email protected]";
const UIAP_HTTP_MEDIA_TYPE = "application/uiap+json";

---

3. Einordnung

[email protected] ist ein konservatives Zusatzbinding.

Es eignet sich für:

• kontrollierte Backend-Integrationen,
• Desktop- oder lokale Host-Setups,
• Deployments, in denen WebSocket organisatorisch oder infrastrukturell unerwünscht ist,
• einfache Controller-zu-Runtime-Kommunikation.

Es ist weniger geeignet für dichte Eventströme wie:

• action.progress
• uiap.workflow.progress
• web.state.delta
• web.signal
• aggressive Heartbeat-Nutzung

Für solche Fälle SOLLTE [email protected] bevorzugt werden.

---

4. Empfohlenes Ressourcenmodell

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;
}

Regeln

1. Die konkrete URI-Struktur ist deployment-spezifisch, MUSS aber dokumentiert werden.
2. Das oben gezeigte Modell ist RECOMMENDED.
3. Neue Sessions SOLLTEN über POST {sessionPath} mit einer session.initialize-Envelope erzeugt werden.
4. Laufende Sessions SOLLTEN über POST {messagePathTemplate} adressiert werden.
5. Server-initiierte Events SOLLTEN über GET {eventStreamPathTemplate} als Server-Sent Events (SSE) geliefert werden.

---

5. Verbindungsaufbau und -abbau

Aufbau

1. Der Client sendet session.initialize per HTTP POST.
2. Der Server antwortet mit genau einer UIAP-Envelope, typischerweise session.initialized oder error.
3. Nach erfolgreicher Initialisierung SOLLTE der Client den Event-Stream der Session öffnen.
4. Danach DÜRFEN weitere UIAP-Requests über den Message-Endpunkt gesendet werden.

Abbau

1. Eine geordnete Session-Beendigung SOLLTE per session.terminate erfolgen.
2. Ein Server KANN zusätzlich DELETE /uiap/sessions/{sessionId} anbieten, MUSS dies aber intern auf session.terminate-Semantik abbilden.
3. Das bloße Schließen einer einzelnen HTTP-Verbindung beendet die UIAP-Session nicht automatisch.

---

6. Framing

6.1 Request/Response-Kanal

1. Eine HTTP-Request-Body MUSS genau eine UIAP-Envelope enthalten.
2. Eine HTTP-Response-Body MUSS genau eine UIAP-Envelope enthalten.
3. Das Media Type SOLLTE application/uiap+json sein.
4. Wenn dieses Media Type nicht praktikabel ist, DARF application/json verwendet werden, solange exakt eine UIAP-Envelope im Body steht.
5. Mehrere UIAP-Envelopes in einem einzigen HTTP-Body SIND nicht konform.
6. Eine leere 202/204-Antwort ohne UIAP-Envelope ist für allgemeine UIAP-Requests nicht interoperabel genug und SOLLTE vermieden werden.

6.2 SSE-Event-Kanal

1. Jedes SSE-Event MUSS genau eine UIAP-Envelope enthalten.
2. Das Event-Feld SOLLTE uiap sein.
3. Der data:-Inhalt MUSS eine JSON-serialisierte UIAP-Envelope sein.
4. Das id:-Feld SOLLTE einen monotonen Stream-Cursor oder Event-Identifier tragen, damit Reconnect nachvollziehbar ist.
5. action.progress, action.result, uiap.workflow.progress, web.state.delta, web.signal und ähnliche server-initiierte Nachrichten SOLLTEN über diesen Kanal gesendet werden.

Beispiel: 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. Fehlerbehandlung

1. HTTP-Fehler vor erfolgreicher UIAP-Verarbeitung, etwa Auth-Fehler, unbekannter Endpoint, falscher Content-Type, Body zu groß oder nicht parsebares JSON, SIND Transport-Fehler.
2. Sobald ein Request als gültige UIAP-Envelope akzeptiert wurde, SOLLTE die fachliche oder protokollseitige Antwort als UIAP-response oder UIAP-error im Body geliefert werden.
3. HTTP-Statuscodes SOLLTEN primär Transport-, Gateway- und Vorverarbeitungsfehler ausdrücken.
4. UIAP-Fehlercodes wie invalid_message, bad_request, unknown_session, session_not_active oder permission_denied gehören in die UIAP-error-Envelope.
5. Wenn der SSE-Stream abbricht, ist das zunächst ein Transportproblem des Event-Kanals, nicht automatisch das Ende der Session.

---

8. Sicherheitsanforderungen

1. https:// SOLLTE Standard sein.
2. Reines http:// DARF nur für Loopback, lokale Entwicklung oder gleichwertig geschützte interne Umgebungen verwendet werden.
3. Authentisierung MUSS pro Deployment geregelt werden, etwa über Bearer-Token, Cookies oder mTLS.
4. Wenn Browser-Clients mit Cookies arbeiten, SOLLTEN CORS- und CSRF-Schutzmechanismen explizit berücksichtigt werden.
5. resumeToken DARF NICHT in URL-Pfaden, Query-Strings oder SSE-Cursorn transportiert werden.
6. Event-Streams DÜRFEN nur für berechtigte Session-Teilnehmer zugänglich sein.

---

9. Reconnect und Session-Resume

1. Der Verlust einer einzelnen HTTP-Verbindung bedeutet nicht automatisch Session-Verlust.
2. Fällt nur der SSE-Stream aus, SOLLTE der Client ihn mit derselben sessionId und dem letzten bekannten Event-Cursor erneut öffnen.
3. Wenn der Server signalisiert, dass der Stream-Cursor nicht mehr fortsetzbar ist oder die Session nicht mehr aktiv ist, SOLLTE der Client session.resume über den Message-Endpunkt senden.
4. Schlägt session.resume fehl, MUSS eine neue Session mit session.initialize begonnen werden.
5. In-flight Requests mit unbekanntem Zustell- oder Ausführungsstatus DÜRFEN nicht blind automatisch wiederholt werden.

---

10. Minimaler Ablauf

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

... weitere Progress-/Result-/Signal-Nachrichten über SSE ...

---

11. Klare Designentscheidung

Ein „REST Binding” für UIAP ist nur dann sauber, wenn man ehrlich zugibt, dass UIAP eben nicht bloß aus statischen CRUD-Operationen besteht. Session-Lifecycle, Progress-Events, Deltas, Resume und Heartbeats verlangen mindestens einen ergänzenden Event-Kanal. Darum ist [email protected] in dieser Form HTTP request/response plus SSE, nicht romantisierte JSON-POST-Folklore.

---

Normative Begriffe

Die Schlüsselwörter MUSS, DARF NICHT, SOLLTE, KANN in diesem Dokument sind normativ gemäss RFC 2119 und BCP 14 zu interpretieren, wenn und nur wenn sie in GROSSBUCHSTABEN erscheinen.

---

Normative Referenzen

• [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 SOLLTE für alle Produktiv-Deployments verwendet werden.
• Authentisierung MUSS pro Deployment geregelt werden (Bearer-Token, Cookies, mTLS).
• resumeToken DARF NICHT in URLs oder Query-Strings transportiert werden.
• SSE-Event-Streams DÜRFEN nur für autorisierte Session-Teilnehmer zugänglich sein.
• CORS- und CSRF-Schutzmechanismen SOLLTEN für Browser-Clients explizit konfiguriert werden.

Changelog

Version	Datum	Änderungen
0.1	2026-03-27	Initialer Entwurf