API Contract — Streamsyncs

developer · v2

API contract

Streamsyncs is delivered as a drop-in UI. Swap the transport for a real REST + WS backend and the UI is unchanged. All resource bodies validate against JSON Schemas exposed at /v1/schemas/{kind}.

REST · resource lifecycle

GET/v1/pipelinesList all pipelines

GET/v1/pipelines/{id}Read pipeline definition

PUT/v1/pipelines/{id}Create or update a pipeline (creates new revision)

POST/v1/pipelines/{id}:validateValidate a draft against JSON Schema

POST/v1/pipelines/{id}:dryRunCompute deployment plan, no side effects

POST/v1/pipelines/{id}:rollbackRollback to a prior revision (?ts=...)

GET/v1/pipelines/{id}/historyList revisions, who/when/diff

POST/v1/pipelines/{id}:runTrigger a manual run

POST/v1/pipelines/{id}:pausePause workers

POST/v1/pipelines/{id}:resumeResume workers

POST/v1/pipelines/{id}:replayReplay from LSN/checkpoint (body: { lsn })

POST/v1/pipelines/{id}:throttleSet max rps (body: { maxRps })

GET/v1/sources, /v1/targets, /v1/schemas, /v1/transforms, /v1/schedulesSame shape as pipelines

GET/v1/runsRun history (?pipeline=&limit=)

GET/v1/team, /v1/tokens, /v1/settingsWorkspace administration

POST/v1/auth/loginMint a session (body: { email, password|sso_token })

POST/v1/auth/logoutRevoke session

WS topics · server → client

WSpipelines.{id}.node.metricsPer-node throughput, lag, CPU, memory

WSpipelines.{id}.node.stateNode lifecycle: running / paused / failed / retrying / done

WSpipelines.{id}.edge.flowRows traversing each DAG edge per tick

WSpipelines.{id}.log.linePer-node log lines (level, msg)

WSpipelines.{id}.runrun.started / run.completed / run.failed / heartbeat

WSpipelines.{id}.alertalert.fired / alert.cleared

WSpipelines.{id}.schemaschema.drift detected on a field

WSpipelines.{id}.checkpointcheckpoint.committed (LSN advance)

WSworkspace.notificationsWorkspace-wide info / warn / success notifications

WSworkspace.ctrlUI → backend control channel (mirrored back for replay)

WSworkspace.authlogin / logout transitions

Commands · client → server (over WS)

CMDpipeline.pause { id }Pause all workers for a pipeline

CMDpipeline.resume { id }Resume paused workers

CMDpipeline.run { id, trigger }Trigger a manual run

CMDpipeline.cancel { id }Cancel the active run

CMDpipeline.throttle { id, maxRps }Cap throughput

CMDpipeline.replay { id, lsn }Rewind checkpoint and replay

CMDnode.pause { pipeline, node }Pause a single DAG node

CMDnode.resume { pipeline, node }Resume a single DAG node

CMDrun.skip { id }Skip the current batch

Integration seam

// 1. Single client module — swap the transport, keep the UI:
window.SsyncClient = {
  rest: { list, get, put, validate, dryRun, rollback, history },
  on(topic, cb)            // subscribe to WS events
  cmd(kind, args)          // send control cmd
  auth: { login, logout, switchWorkspace }
}

// 2. Per-resource React hooks — backed by an injectable transport:
const [doc, ops] = useResource('pipelines', 'p_orders_lake');
const events     = useStream('pipelines.p_orders_lake.node.metrics', cb);
const buffer     = useEventBuffer();
const user       = useUser();
const note       = useNotifications();

// 3. JSON Schemas live at runtime for any kind:
window.SsyncSchemas.pipelines  // ← drop into Ajv, monaco-yaml, etc.

Mock backend controls

DEVSsyncClient.resetSeed()Wipe localStorage and re-seed. Also a button on the Debug drawer.

DEVSsyncClient.setEventRate(rps)Throttle the simulated event firehose (default 62/s).