Why
Once #254 persists recordings, nothing can read them. The portal viewer needs a
run list it can poll while a user fires requests from the playground, and a
detail payload it can overlay on the canvas.
This is the API half of #208.
What
Project-scoped, ACL enforced, alongside the existing route endpoints.
List runs for a project, filterable by route, outcome and time, paginated,
newest first. This is polled by the portal while the execution tab is open, so
it must be cheap: it serves the run headers only — no spans — and is backed by
the (projectId, startedAt desc) index.
Return enough for a list row without a second call: outcome, status code,
start time, duration, span count, and the truncated/dropped flags. A recording
that dropped spans is incomplete and the UI has to say so rather than quietly
showing a partial graph.
Run detail — one run with its spans, ordered by seq. Spans carry
parentSeq, so the response is a flat list the client can tree itself; do not
nest it server-side.
Delete — a run, and all runs for a route. Recordings are debug data and the
user needs a way to clear them without waiting for retention to catch up.
Notes
- The toggle write path already exists and needs no work here:
PATCH /v1/:projectId/routes/:id (api/v1/routes/update-partial) accepts
recordExecution, tracingEnabled, timeoutSeconds and active.
- Editing
recordExecution triggers a recompile — it is stamped into the route
artifact. Not cosmetic, and the UI is told to reflect that.
- Span
input/output are already truncated at record time against a per-span
cap. Do not re-truncate at read time; the stored truncated flag is what the
viewer renders.
- Follow the existing
test-suites run endpoints for pagination shape and
requireProjectAccess usage — the portal's run history already consumes that
shape and there is no reason for a second one.
Depends on #254.
Why
Once #254 persists recordings, nothing can read them. The portal viewer needs a
run list it can poll while a user fires requests from the playground, and a
detail payload it can overlay on the canvas.
This is the API half of #208.
What
Project-scoped, ACL enforced, alongside the existing route endpoints.
List runs for a project, filterable by route, outcome and time, paginated,
newest first. This is polled by the portal while the execution tab is open, so
it must be cheap: it serves the run headers only — no spans — and is backed by
the
(projectId, startedAt desc)index.Return enough for a list row without a second call: outcome, status code,
start time, duration, span count, and the truncated/dropped flags. A recording
that dropped spans is incomplete and the UI has to say so rather than quietly
showing a partial graph.
Run detail — one run with its spans, ordered by
seq. Spans carryparentSeq, so the response is a flat list the client can tree itself; do notnest it server-side.
Delete — a run, and all runs for a route. Recordings are debug data and the
user needs a way to clear them without waiting for retention to catch up.
Notes
PATCH /v1/:projectId/routes/:id(api/v1/routes/update-partial) acceptsrecordExecution,tracingEnabled,timeoutSecondsandactive.recordExecutiontriggers a recompile — it is stamped into the routeartifact. Not cosmetic, and the UI is told to reflect that.
input/outputare already truncated at record time against a per-spancap. Do not re-truncate at read time; the stored
truncatedflag is what theviewer renders.
test-suitesrun endpoints for pagination shape andrequireProjectAccessusage — the portal's run history already consumes thatshape and there is no reason for a second one.
Depends on #254.