JustAPI

A node-based API explorer. Drop requests on a canvas, chain response values into the next request, and run whole flows. Import cURL, fetch, HAR, or OpenAPI and fan endpoints out as nodes.

Stack

• Next.js 15 (App Router)
• React 18
• @xyflow/react (React Flow) for the canvas
• Zustand for state
• Tailwind CSS

Develop

pnpm install
pnpm dev

Build

pnpm build
pnpm start

Layout

• app/ — Next route files: page.tsx renders the canvas; api/flows + api/agent (the agent bridge), api/proxy (+ multipart), and api/share routes; root layout.tsx.
• src/canvas/ — the client app:
  • use-canvas-store.ts — persisted graphs (nodes/edges/viewport, multiple named canvases).
  • use-run-store.ts — in-memory per-node run state (responses are never persisted).
  • engine.ts — chain execution: topological upstream resolution, cycle detection, variable/header bindings.
  • execute-request.ts — pure send pipeline (auth headers, {{var}} substitution, JSON validation).
  • get-path.ts — data.token / status / headers.etag extraction from responses.
  • flow-spec.ts / materialize.ts — the declarative flow spec (parse/validate) and spec → live graph.
  • parse-curl.ts / parse-openapi.ts — importers behind the import dialog.
  • use-agent-sync.ts — subscribes the browser as the execution host for agent-pushed flows (SSE).
  • components/ — request/collection/assert nodes, binding edge + inspector, rail, library, status bar, import dialog.
• src/server/ — server-side flow layer:
  • agent-hub.ts — in-memory hub (flows persisted to .justapi/flows/*.json); SSE broadcast + run long-polling.
  • run-flow-spec.ts — headless executor that mirrors the browser engine's semantics and report shape.
• mcp/server.mjs — stdio MCP server exposing flows as tools (pnpm mcp).
• src/stores/use-environment-store.ts — environments with {{variable}} substitution.
• src/utils/ — http (proxy fetch), variables, har, theme plumbing.
• extension/ — standalone MV3 Chrome extension that intercepts fetch/XHR. Currently not wired to the canvas (the in-app debugger UI was removed); HAR import works from pasted .har files.

Concepts

• Request node — method, URL, headers, body, auth; run it and the response renders inline. ⌘↵ runs the selected node; double-click ▶ re-runs the whole chain.
• Binding edge — connect node A → node B and pick a value from A's response (data.token, status, headers.etag); it feeds B as a {{variable}} or a header. Running B runs its upstream chain first (topological order, cycles rejected).
• Origin node — the root of a flow tree, named after a collection. Requests are added from it and branch off each other; every request in the tree shows a membership badge. ▶ on the origin runs the whole tree in dependency order. The origin also carries the tree's environment (expandable variable editor); precedence: edge bindings > origin env > active environment.
• Assert node — hangs off a request and grades its response (status = 200, data.id exists, contains/>/<). Checks evaluate live as responses arrive, and the flow verdict counts them: "4 passed · 2 checks ✓".

Agents

JustAPI doubles as the UI an AI agent uses to prove a backend works: push a declarative flow spec over HTTP (POST /api/flows), watch it materialize on the open canvas, run it (POST /api/flows/:slug/run), and get a machine-readable verdict — while the human supervises the tree executing live. With no canvas connected (CI, background agents) runs execute headless server-side with the same report. An MCP server (pnpm mcp) exposes the same as native tools for Claude Code and other MCP clients. See docs/agent-api.md.

Outgoing requests

The browser calls /api/proxy, which forwards to the target URL server-side. This sidesteps CORS for arbitrary endpoints.

Persistence

Graphs (nodes, edges, viewport) persist to localStorage (justapi-canvas). Responses are kept in memory only. Share links (/?s=ID) resolve via /api/share (Vercel Blob) and spawn a request node; legacy /playground?s=ID links redirect here.