Skip to content
XMachines

RFC: REST (v1)

Status: Draft
Version: v1
Scope: HTTP projection of machines and runs
Non-goals: Execution semantics, durability policy

1. Purpose

REST provides an HTTP projection over machines and runs.

REST defines representation only, never execution behavior.

2. Core Principles

  • REST is optional
  • REST is stream-native
  • REST is projection-only

3. Machine Endpoints

GET /m/<machineRef>

Content negotiation MAY return:

  • application/json
  • text/markdown
  • application/schema+json

4. Run Endpoints

GET /r/<runRef>

Default (application/json):

  • returns latest snapshot

Streaming (explicit via Accept):

  • application/x-ndjson
  • text/event-stream

5. Mutations

PATCH /r/<runRef>

Single event

  • JSON body
  • applies one event
  • returns resulting snapshot

Multiple events

  • NDJSON body
  • atomic
  • returns resulting snapshot

PATCH never streams.

6. HTTP Verbs

VerbMeaning
GETread / stream
POSTcreate run
PATCHapply events
PUTunused

7. Invariants

  1. PATCH always returns snapshot
  2. Streaming is GET-only
  3. Content negotiation affects framing only

8. Lock statement

REST is a projection over runs and machines.
It defines representation only.
This is REST v1.