API Designer

API Designer — API Design, Documentation, Mocking, and Testing Pipeline

An agent team collaborates to generate API design, schema, documentation, and mock/tests in a single pass.

Execution Mode

Agent Team — 5 members communicate directly via SendMessage and cross-validate each other's work.

Agent Composition

Workflow

Phase 1: Preparation (Performed directly by the orchestrator)

1. Extract from user input:
   • Domain: What service is the API for
   • Paradigm: REST / GraphQL / Hybrid
   • Key Resources: List of core entities
   • Authentication Method (optional): OAuth, JWT, API Key
   • Existing Files (optional): Existing schemas, documentation, code, etc.
2. Create the _workspace/ directory at the project root
3. Organize the input and save to _workspace/00_input.md
4. If existing files are provided, copy them to _workspace/ and skip the corresponding phase
5. Determine the execution mode based on the scope of the request

Phase 2: Team Assembly and Execution

Tasks 3a (documentation) and 3b (tests) are executed in parallel.

Inter-team communication flow:

• api-architect completes -> Delivers resource model to schema-validator, endpoints to doc-writer, request/response examples to mock-tester
• schema-validator completes -> Delivers schema to doc-writer, schema-based examples to mock-tester
• doc-writer <-> mock-tester: Mutually verify that documentation examples and mock responses match
• review-auditor cross-validates all artifacts. When 🔴 must-fix issues are found, requests revisions from the relevant agent -> rework -> re-verify (up to 2 rounds)

Phase 3: Integration and Final Artifacts

Organize the final artifacts based on the review report:

1. Verify all files in _workspace/
2. Confirm that all 🔴 must-fix items from the review report have been addressed
3. Report the final summary to the user

Mode by Task Scale

Leveraging existing files: If the user provides schemas, documentation, or other existing files, skip the corresponding steps.

Data Transfer Protocol

File naming convention: {order}_{agent}_{artifact}.{extension}

Error Handling

Test Scenarios

Normal Flow

Prompt: "Design a REST API for an e-commerce platform. I need product, order, user, and cart resources" Expected Result:

• API Design: 4 resources, CRUD endpoints, relationship modeling, authentication design
• Schema: OpenAPI 3.1 YAML, all model type definitions
• Documentation: Quick start + endpoint reference + error codes
• Tests: Per-resource CRUD tests + authentication tests + load scenarios
• Review: All items in the alignment matrix verified

Existing File Flow

Prompt: "Create API docs and tests from this OpenAPI schema" + schema file Expected Result:

• Copy existing schema to _workspace/02_schema.yaml
• Merged documentation + test mode: deploy doc-writer + mock-tester + review-auditor
• Skip api-architect and schema-validator

Error Flow

Prompt: "Design an API quickly, blog platform" Expected Result:

• Insufficient domain information -> api-architect infers standard blog resources (Post, Comment, User, Tag)
• Execute in full pipeline mode
• Review report notes "design based on inferred domain requirements"

Agent Extension Skills

Extension skills that enhance each agent's domain expertise: