--- path: /studio/aja/api-endpoints surface: studio domain: aja auth: signed-in + studio entitlement source: apps/oshun/web/src/app/studio/aja/api-endpoints/page.tsx status: walked + e2e-covered last_walked: '2026-07-02 developer-ops lane addendum — Playwright real-dev-infra coverage now proves signed-in render, route-map contract, quick-action href order, ready route-conflict detector, 44 px primary targets, invalid-JSON client guard with no POST, real conflict-group result, duplicate-route BFF error, workflow pass/fail client-state controls, parity report derivation, fail-closed loading/unauthorized/catalog-error states, mobile no-overflow, and direct BFF 401/403/400/200 gates for catalog and analyze. Spec: apps/oshun/web/e2e/studio-aja-developer-ops-lane-consoles.spec.ts.' '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data (2xx), console/page-errors, expected content, screenshot verified; live screen-reader, touch, offline, and telemetry-delivery checks pending a manual AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body re-derived 2026-06-03 from current source (lane-console architecture)' --- # Aja API Endpoints ## Purpose The real, backend-wired slice of this workspace is the `ApiRouteConflictLane`: a route conflict detector wired via `/v1/admin/aja/api-endpoints` — it analyzes a set of declared API routes, derives each route's normalized shape, groups colliding shapes, and reports which routes conflict. The same component also retains an in-page (no `/v1`) scaffolding section — a Capability Summary, 18 workflow tracks with client-side run/pass-fail state, an Automated API Parity Checks panel, and a Telemetry/Alerting/Runbooks panel — and emits workspace mount/unmount analytics. ## Entry points - **Direct URL** — `/studio/aja/api-endpoints` (signed-in + studio entitlement) - **Sibling quick-actions from this page** — Python SDK, Back to Studio ## Layout regions `page.tsx` mounts `ShellLayout` with `active="studio"` and renders three panels. - **Workspace panel** (`data-aja-api-endpoints-workspace`): - `

` "Aja API Endpoints Workspace" (via `WorkspaceHeading`) - `

` — "Dedicated API Endpoints route with dense expert-mode controls, progressive disclosure, and canonical route map." - **Route Conflict Detector lane** (`section data-are-lane`, `

` "Live Route Conflict Detector") — the real-backed slice - **Capability Summary** panel (`data-aja-api-endpoints-capability-summary`, `

` "Capability Summary" + `data-aja-api-endpoints-capability` cards — static copy) - **Workflow track sections** — one `
` per `AJA_API_WORKFLOW_TRACKS` entry (18 tracks, e.g. `data-aja-api-endpoints-authentication-workflow`), each `

` with workflow rows holding in-page run controls - `data-aja-api-endpoints-workflow-notice` + `data-aja-api-endpoints-workflow-summary` - **Automated API Parity Checks** panel (`data-aja-api-endpoints-parity`) - **Telemetry, Alerting, and Runbooks** panel (`data-aja-api-endpoints-telemetry`) - **Route Map panel** (`data-aja-api-endpoints-route-map`): `

` "Route Map" + one `
` per `STUDIO_AJA_API_ENDPOINTS_ROUTE_MAP` entry (5 entries) - **Quick actions panel**: `.quickAction` ``s — see Interactions ## States These states belong to the real `ApiRouteConflictLane`: - [x] **Loading** — `data-are-loading` "Loading route conflict detector…" - [x] **Unauthorized** — on 401/403, `data-are-unauthorized` (admin-scope reason, default "Aja workspace scope required to analyze routes.") - [x] **Error** — non-OK / malformed / unreachable → `data-are-error` - [x] **Ready (form)** — `data-are-form` with the JSON payload textarea - [x] **Result** — `data-are-result`: `data-are-headline` (shapes · `data-are-collision-groups` · `data-are-conflict-count`) and a `data-are-routes` table (`data-are-route-shape`, `data-are-route-conflict`) - [x] **Validation error** — `data-are-analyze-error` for client JSON parse errors and BFF schema errors (for example duplicate route IDs). The retained scaffolding panels (Capability Summary, workflow tracks, parity, telemetry) render statically and hold only client-side React state; they do not hit `/v1` and have no loading/unauthorized/error of their own. ## Interactions ### Route Conflict Detector form (`data-are-form`) — real backend - [x] **API routes JSON** — `textarea data-are-payload` - [x] **Analyze routes** — `button data-are-submit`; `POST /v1/admin/aja/api-endpoints/analyze` with the parsed JSON → `{ result: AreResult }` ### Retained in-page scaffolding (no `/v1`) - [x] **Workflow rows** — per `AjaApiWorkflowId`: `Force failure` (`data-aja-api-endpoints-workflow-failure-toggle`), `Run workflow` (`data-aja-api-endpoints-workflow-run`), status / runs readouts — all client-side state only - [x] **Run API parity checks** — `data-aja-api-endpoints-parity-run` derives a pass/fail report from the current in-page workflow statuses - [x] **Runbook links** — `data-aja-api-endpoints-runbook-link` static ``s ### Route Map panel (`data-aja-api-endpoints-route-map`) - [x] **Route entries** — non-interactive `
` blocks from `STUDIO_AJA_API_ENDPOINTS_ROUTE_MAP` (5 entries): `/studio/aja/api-endpoints` plus `…/scenes/[sceneId]`, `…/exports/[exportId]`, `…/revisions/[revisionId]`, `…/governance/[policyId]`. ### Quick actions panel - [x] **Open Aja Python SDK workspace** → `/studio/aja/python-sdk` - [x] **Back to Studio workspace index** → `/studio` ## E2E coverage - [`apps/oshun/web/e2e/studio-aja-developer-ops-lane-consoles.spec.ts`](../../../../apps/oshun/web/e2e/studio-aja-developer-ops-lane-consoles.spec.ts) covers signed-in shell render, ready detector form, invalid JSON client guard with no `POST`, real conflict-group output (`3 shapes · 1 collision groups · 3 conflicting`), duplicate route ID BFF error rendering, 36 workflow rows, pass/fail workflow state, parity report derivation, route-map count, exact quick-action hrefs, 44 px primary targets, loading / unauthorized / malformed-catalog fail-closed states, mobile no-overflow, and direct BFF auth/schema/happy-path gates. ## Data & contracts - **Reads**: `GET /v1/admin/aja/api-endpoints` on mount (response read but only used to gate the conflict-detector lane to ready after validating the `methods` catalog shape) via `buildBffAuthHeaders()`, `cache: 'no-store'` - **Writes**: `POST /v1/admin/aja/api-endpoints/analyze` → `{ result: AreResult }`. The workflow-track / parity controls perform NO BFF writes — they mutate client-side React state only - **Realtime**: none - **Caching**: SSR shell; the conflict-detector lane fetches client-side on mount (no-store) - **Telemetry**: the workspace emits `emitStudioWorkspaceMount` / `emitStudioWorkspaceUnmount` (workspaceId `aja-api-endpoints`) on mount/unmount - **Auth**: BFF endpoints admin-scoped + fail-closed (401/403 → unauthorized render on the lane); the route is signed-in + studio (proxy gate) ## Cross-references - Parent: [`../../studio-overview.md`](../../studio-overview.md) - Component sources: - `apps/oshun/web/src/components/studio/StudioAjaApiEndpointsWorkspace.tsx` - `apps/oshun/web/src/components/studio/StudioAjaApiEndpointsRouteMap.ts` - Sibling from quick-actions: `/studio/aja/python-sdk` ## Known downstream boundaries - The 18 workflow tracks, the parity panel, and the telemetry/alerting panel are in-page scaffolding (client state only) — confirm whether they should be wired to real BFF endpoints or removed in favour of the conflict-detector - Route-map sub-routes are descriptive contracts; implementation status of those child pages is tracked separately from this leaf console. - The exact studio entitlement/proxy policy for `/studio/aja/*` is documented in shell/auth surfaces, not repeated in this leaf doc.