Engine

5.3. Requests and responses🔗

POST /append takes a JSON list of events: entity, type, the key under the entity's key field name, optional expected_revision, the fields.

A charge of 12.50 to folio F-1042, as the client sends it:

[
  {
    "entity": "folio",
    "type": "ChargePosted",
    "folio_id": "F-1042",
    "charge_id": "C1",
    "gross_minor": "12.50",
    "expected_revision": 1
  }
]
🔗def
Spec.decodeEvent (sc : Schema) (keys : List (String × String)) (now : Rat) (i : Nat) (j : Json) : Except WireError Event
Spec.decodeEvent (sc : Schema) (keys : List (String × String)) (now : Rat) (i : Nat) (j : Json) : Except WireError Event

An event as sent: entity, type, the key under the entity's key field name (keys), optional expected_revision, the fields. Its at is the engine's clock reading now.

🔗inductive type

Why a request is not a batch of events. i is the event's index in the batch.

Spec.WireError.notJson : WireError

the body is not JSON

Spec.WireError.notList : WireError

the body is not a list

Spec.WireError.notObject (i : Nat) : WireError

an event is not an object

Spec.WireError.missing (i : Nat) (name : String) : WireError

entity, type or the key field is missing or not a text

Spec.WireError.unknownEntity (i : Nat) (entity : String) :
  WireError

no deployed entity has this name (so its key field is unknown)

Spec.WireError.badRevision (i : Nat) : WireError

expected_revision is not a natural number

Spec.WireError.reserved (i : Nat) (name : String) :
  WireError

key, at, revision or position: an engine field the request can't set

Spec.WireError.duplicate (i : Nat) (name : String) :
  WireError

a name twice in one event

Spec.WireError.notScalar (i : Nat) (field : String) :
  WireError

a field holds a list or an object

An accepted batch is answered with status 200 and, per event, its position, revision and at:

{"events":[{"position":7,"revision":2,"at":"2026-12-01T10:00:00Z"}]}
appendedResponseText · checked against the spec ·

An accepted batch is answered with status 200 and the response text.

🔗def

The stamp of appendedResponseText.

A rejected batch is answered with status 409, the index of the event, the position it would have had and the check it fails:

{"rejected":{"index":0,"position":7,"reason":{"check":"expected_revision","expected":1,"actual":2}}}
rejectedResponseText · checked against the spec ·

A rejected batch is answered with status 409 and the response text.

🔗def

The rejection of rejectedResponseText.