API Workshop

Workflow

Phase 1: Context Gathering (Main Agent)

Before spawning the workshop agents:

1. If given a description: Extract requirements, constraints, and success criteria
2. If given a URL: Fetch the existing API spec and summarize it
3. Identify domain entities: List the core resources/types involved
4. Clarify open questions: Ask user if anything is ambiguous
5. Create initial context document: workspace/api-context.md

Phase 2: Initial Proposals (Sub-agents 1-5)

Spawn all five agents in parallel. Each receives:

• The context document from Phase 1
• Their agent instructions (from agents/*.md)
• The API design reference (REFERENCE.md)

Each agent independently:

1. Proposes an initial design approach
2. Creates example endpoint/schema definitions
3. Writes their rationale and concerns
4. Saves to workspace/proposals/<agent-name>.md

Phase 3: Cross-Examination (Main Agent Orchestrates)

For each significant design decision, run a mini-debate:

1. API Style (REST vs GraphQL vs RPC)

   • API Designer proposes based on UX
   • Performance Analyst challenges based on query patterns
   • Tech Lead weighs standardization concerns

2. Authentication Strategy (OAuth2, API keys, JWT)

   • Security Auditor proposes approach
   • API Designer challenges if it adds friction
   • Tech Lead validates against standards

3. Versioning Strategy (URI, header, content negotiation)

   • Tech Lead proposes approach
   • API Designer challenges impact on consumers
   • Domain Modeler validates semantic compatibility

4. Resource Design (granularity, relationships, operations)

   • Domain Modeler proposes structure
   • Performance Analyst challenges N+1 issues
   • API Designer validates developer experience

5. Error Handling (status codes, error formats, problem details)

   • Security Auditor proposes secure defaults
   • API Designer ensures clarity for consumers
   • Tech Lead validates RFC 7807 compliance

For each debate:

• Present the question and stakes
• Let 2-3 agents argue their positions
• Synthesize the decision with rationale
• Document trade-offs considered

Phase 4: Synthesis (Main Agent)

After all debates complete:

1. Reconcile proposals: Merge agent input into coherent design
2. Resolve conflicts: Make final calls on contested decisions
3. Document rationale: Explain why each choice was made
4. Identify risks: Note what could go wrong and mitigations
5. Generate specification: Create complete API spec in requested format

Phase 5: Output

Generate the final deliverable following the template in REFERENCE.md:

1. Executive Summary: High-level design decisions and rationale
2. Architecture: API style, auth, versioning, error handling
3. Specification: Complete OpenAPI/GraphQL schema
4. Design Rationale: Why each major decision was made
5. Trade-offs: What was considered and rejected
6. Implementation Notes: Tips for backend developers
7. Client Examples: Sample requests/responses in multiple languages

Save to workspace/api-specification.md and present to the user.

Debate Topics

The workshop should address these key decisions:

API Style

• REST: Resource-oriented, HTTP semantics, wide tooling
• GraphQL: Flexible queries, type-safe, learning curve
• RPC: Simple, efficient, less discoverable

Versioning

• URI versioning: /v1/users (explicit, breaks caching)
• Header versioning: Accept: application/vnd.api+json;version=1 (clean URIs, harder to test)
• Content negotiation: Media types control breaking changes

Authentication

• OAuth2: Standard, complex setup, great for delegated auth
• API keys: Simple, less secure, good for server-to-server
• JWT: Stateless, revocation challenges, flexible claims

Pagination

• Offset/limit: Simple, inconsistent under writes
• Cursor-based: Consistent, opaque, harder to jump to page N
• Keyset: Efficient, requires indexed sort key

Error Handling

• Problem Details (RFC 7807): Structured, extensible, standard
• Custom format: Tailored to domain, non-standard
• HTTP status only: Simple, lacks detail

Output Structure

workspace/
├── api-context.md                  # Phase 1 context gathering
├── proposals/
│   ├── api-designer.md
│   ├── domain-modeler.md
│   ├── security-auditor.md
│   ├── performance-analyst.md
│   └── tech-lead.md
├── debates/
│   ├── api-style-debate.md
│   ├── auth-strategy-debate.md
│   ├── versioning-debate.md
│   ├── resource-design-debate.md
│   └── error-handling-debate.md
└── api-specification.md            # Final deliverable

Coordinator Responsibilities

1. Gather context and clarify requirements with user
2. Spawn proposal agents in parallel
3. Orchestrate debates on key design decisions
4. Ensure all agents engage (not just API Designer)
5. Synthesize final specification with rationale
6. Present deliverable to user
7. Offer to generate client SDKs or mock server if requested

Customization

The user can customize the workshop by:

• Skipping agents: "Skip performance, focus on security"
• Adding constraints: "Must support GraphQL subscriptions"
• Specifying style: "Design a REST API following JSON:API spec"
• Setting priorities: "Optimize for developer experience over efficiency"
• Providing examples: "Similar to Stripe's API" or "Here's our existing API"
• Requesting specific debates: "Debate whether we need versioning at all"

Adapt the agent roster and debate topics accordingly.

Example Invocations

/api-workshop design an API for a task management system

/api-workshop review https://api.example.com/openapi.json

/api-workshop design a GraphQL API for e-commerce with subscriptions

/api-workshop compare REST vs GraphQL for our social network

The workshop adapts to whether you're designing new, reviewing existing, or comparing alternatives.