just-vibeAPIs · plan by default
/api-design
Define endpoints, resources, validation, and response contracts
Use to design consumer-visible operations; backend-service implements business behavior.
Make it your own.
In Claude Code, use the slash command and add your context. In Codex, select api-design from the just-vibe skill picker, then send the same brief.
Version 0.11.0 also supports /jv api-design, /just-vibe api-design and /jv:api-design in Claude. See shortcut setup and context examples.
/just-vibe:api-design Design invitation endpoints with explicit expiry and conflict responses./just-vibe:api-design Design an asynchronous export API that can fail after acceptance./just-vibe:api-design Draft an API with unknown consumer constraints; mark compatibility assumptions.What the agent does
- Inspect domain conventions, existing APIs and actual consumer journeys.
- Define resource identity, method semantics, validation, authorization, errors and versioning consistently with them, with one success and one failure exchange per operation.
- Check consumer usability and migration needs.
Inputs
- resources/actions, consumers, access rules, and compatibility requirements.
Optional context: scope, references, constraints, successCriteria, environment, mode, budget.
Scope
- Reads
- Endpoint/interface shape, validation, response/error contracts, and evolution.
- Writes
- No source changes in inspect/plan. Save only requested planning artifacts. A separately requested repair uses the relevant implementation workflow.
- Mode
- Plan; resources/actions, consumers, access rules, and compatibility requirements.
- Prerequisites
- Interface definitions, producer/consumer source, authentication model, versioning constraints, and isolated test endpoints. External API calls must respect environment, credentials, rate limits, and side-effect scope.
Expected output
- API proposal with request/response examples, status and error meanings, invariants, acceptance scenarios and consumer compatibility notes.
How the work is checked
- Invalid and unauthorized requests have defined outcomes; new behavior does not silently break an existing consumer.
When to stop or clarify
- Do not choose unresolved business policy or implement endpoints during a design-only request.
Handling missing context
- Infer
- Read producer/consumer schemas, error contracts, auth conventions and known supported client versions.
- Assume
- Keep compatible response and pagination semantics where the brief does not request a breaking change.
- Ask
- Ask when contract sources disagree or an unknown consumer changes compatibility; do not require live credentials to write or test an isolated client.
Technical guidance
- Evidence
- Read consumer needs, resource ownership, identity, transport constraints and current serializer behavior.
- Method
- Specify valid/error exchanges, missing versus null, units, limits, idempotency and authorization before editing handlers.
- Pitfall
- Consistent JSON shape alone does not establish consistent business meaning or access control.
- Check
- Exercise representative valid, invalid, unauthorized and dependency-failure requests against the actual handler boundary.
Situational decisions
When a proposed endpoint hides several independently failing effects: Expose operation state or explicit partial-failure semantics instead of implying atomic success.
The coding agent follows this workflow using its available tools. Installation does not grant service access or guarantee an outcome. Read the compatibility notes.