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):
  • <h1> "Aja API Endpoints Workspace" (via WorkspaceHeading)
  • <p data-aja-api-endpoints-summary> — "Dedicated API Endpoints route with dense expert-mode controls, progressive disclosure, and canonical route map."
  • Route Conflict Detector lane (section data-are-lane, <h2 data-are-heading> "Live Route Conflict Detector") — the real-backed slice
  • Capability Summary panel (data-aja-api-endpoints-capability-summary, <h2> "Capability Summary" + data-aja-api-endpoints-capability cards — static copy)
  • Workflow track sections — one <section> per AJA_API_WORKFLOW_TRACKS entry (18 tracks, e.g. data-aja-api-endpoints-authentication-workflow), each <h2> 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): <h2> "Route Map" + one <article> per STUDIO_AJA_API_ENDPOINTS_ROUTE_MAP entry (5 entries)
• Quick actions panel: .quickAction <Link>s — see Interactions

States#

These states belong to the real ApiRouteConflictLane:

• Loading — data-are-loading "Loading route conflict detector…"
• Unauthorized — on 401/403, data-are-unauthorized (admin-scope reason, default "Aja workspace scope required to analyze routes.")
• Error — non-OK / malformed / unreachable → data-are-error
• Ready (form) — data-are-form with the JSON payload textarea
• 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)
• 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#

• API routes JSON — textarea data-are-payload
• 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)#

• 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
• Run API parity checks — data-aja-api-endpoints-parity-run derives a pass/fail report from the current in-page workflow statuses
• Runbook links — data-aja-api-endpoints-runbook-link static <a>s

Route Map panel (data-aja-api-endpoints-route-map)#

• Route entries — non-interactive <article> 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#

• Open Aja Python SDK workspace → /studio/aja/python-sdk
• Back to Studio workspace index → /studio

E2E coverage#

• 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
• 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.