Back to Details

api-workshop

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Workshop

API研讨会

A debate-driven multi-agent workshop for designing and reviewing APIs. Five specialized agents propose designs and challenge each other to produce a well-reasoned API specification.
这是一个用于API设计与评审的辩论式多Agent研讨会。五个专业Agent会提出设计方案并相互质疑，最终产出一份论证充分的API规范。

Prerequisites

前置条件

Agents will need access to API design patterns and standards. The 
REFERENCE.md
file provides OpenAPI templates, design principles, and debate prompts.
Agent需要能够获取API设计模式与标准。
REFERENCE.md
文件提供了OpenAPI模板、设计原则以及辩论提示语。

Inputs

输入信息

The user provides:
  1. API Description (required) — What the API should do, or URL to existing spec
  2. Context (optional) — Business domain, constraints, existing systems
  3. Focus areas (optional) — Which aspects matter most (see Agent Roster below)
  4. Format preference (optional) — OpenAPI 3.x, GraphQL schema, AsyncAPI
If the user provides a URL to an existing spec, agents will review it rather than design from scratch.
用户需要提供：
  1. API描述（必填）—— API需实现的功能，或现有规范的URL
  2. 上下文信息（可选）—— 业务领域、约束条件、现有系统情况
  3. 重点关注领域（可选）—— 哪些方面最为重要（参见下方Agent角色列表）
  4. 格式偏好（可选）—— OpenAPI 3.x、GraphQL schema、AsyncAPI
如果用户提供现有规范的URL，Agent会直接评审该规范，而非从零开始设计。

Agent Roster

Agent角色列表

Each agent brings a specialized perspective and debates with others:
#AgentFocusChallenges
1API DesignerConsumer UX, discoverability, naming"Is this intuitive for developers?"
2Domain ModelerCorrect modeling, consistency, DDD"Does this match the domain?"
3Security AuditorAuth/authz, data exposure, OWASP"What are the security risks?"
4Performance AnalystEfficiency, caching, over/under-fetching"Will this scale?"
5Tech LeadStandards compliance, versioning, docs"Does this follow best practices?"
每个Agent都具备专业视角，并会与其他Agent展开辩论：
#Agent关注重点质疑方向
1API Designer用户体验、可发现性、命名规范"这对开发者来说是否直观？"
2Domain Modeler建模准确性、一致性、领域驱动设计(DDD)"这是否与业务领域匹配？"
3Security Auditor认证/授权、数据暴露、OWASP标准"存在哪些安全风险？"
4Performance Analyst效率、缓存机制、数据过度/不足获取"该API能否横向扩展？"
5Tech Lead标准合规性、版本控制、文档"这是否遵循最佳实践？"

Workflow

工作流程

Phase 1: Context Gathering (Main Agent)

阶段1：上下文收集（主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
在启动研讨会Agent之前：
  1. 若提供功能描述：提取需求、约束条件与成功标准
  2. 若提供URL：获取现有API规范并生成摘要
  3. 识别领域实体：列出涉及的核心资源/类型
  4. 澄清模糊问题：询问用户是否存在不明确的内容
  5. 创建初始上下文文档：
    workspace/api-context.md

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

阶段2：初始方案提议（子Agent 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
并行启动所有五个Agent。每个Agent会收到：
  • 阶段1生成的上下文文档
  • 各自的Agent指令（来自
    agents/*.md
    ）
  • API设计参考文档（
    REFERENCE.md
    ）
每个Agent独立完成以下工作：
  1. 提出初始设计思路
  2. 创建示例端点/ schema定义
  3. 撰写设计理由与关注点
  4. 保存至
    workspace/proposals/<agent-name>.md

Phase 3: Cross-Examination (Main Agent Orchestrates)

阶段3：交叉质询（主Agent统筹）

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
针对每个重要设计决策，开展小型辩论：
  1. API风格（REST vs GraphQL vs RPC）
    • API Designer基于用户体验提出方案
    • Performance Analyst基于查询模式提出质疑
    • Tech Lead考量标准化相关问题
  2. 认证策略（OAuth2、API keys、JWT）
    • Security Auditor提出方案
    • API Designer质疑是否会增加使用门槛
    • Tech Lead验证是否符合标准
  3. 版本控制策略（URI、请求头、内容协商）
    • Tech Lead提出方案
    • API Designer质疑对用户的影响
    • Domain Modeler验证语义兼容性
  4. 资源设计（粒度、关联关系、操作）
    • Domain Modeler提出结构方案
    • Performance Analyst质疑N+1查询问题
    • API Designer验证开发者体验
  5. 错误处理（状态码、错误格式、问题详情）
    • Security Auditor提出安全默认方案
    • API Designer确保对用户清晰易懂
    • Tech Lead验证是否符合RFC 7807标准
针对每场辩论：
  • 提出议题与影响
  • 让2-3个Agent阐述各自立场
  • 综合决策并说明理由
  • 记录已考虑的权衡因素

Phase 4: Synthesis (Main Agent)

阶段4：方案整合（主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
所有辩论完成后：
  1. 协调方案：将各Agent的输入整合为连贯的设计
  2. 解决冲突：对有争议的决策做出最终判断
  3. 记录设计理由：解释每个选择的依据
  4. 识别风险：标注可能出现的问题与缓解措施
  5. 生成规范文档：按照用户要求的格式创建完整的API规范

Phase 5: Output

阶段5：输出成果

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.
根据
REFERENCE.md
中的模板生成最终交付物：
  1. 执行摘要：高层设计决策与理由
  2. 架构说明：API风格、认证、版本控制、错误处理
  3. 规范文档：完整的OpenAPI/GraphQL schema
  4. 设计理由：每个重大决策的依据
  5. 权衡因素：已考虑并否决的方案
  6. 实现提示：给后端开发者的建议
  7. 客户端示例：多语言的请求/响应示例
保存至
workspace/api-specification.md
并提交给用户。

Debate Topics

辩论议题

The workshop should address these key decisions:
研讨会需要解决以下关键决策：

API Style

API风格

  • REST: Resource-oriented, HTTP semantics, wide tooling
  • GraphQL: Flexible queries, type-safe, learning curve
  • RPC: Simple, efficient, less discoverable
  • REST：面向资源、HTTP语义、工具生态丰富
  • GraphQL：查询灵活、类型安全、学习曲线较陡
  • RPC：简单直接、效率高、可发现性差

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
  • URI版本控制：
    /v1/users
    （直观明确，破坏缓存）
  • 请求头版本控制：
    Accept: application/vnd.api+json;version=1
    （URI简洁，测试难度高）
  • 内容协商：通过媒体类型控制破坏性变更

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
  • OAuth2：标准化、配置复杂、适用于委托授权场景
  • API keys：简单易用、安全性较低、适用于服务器间通信
  • JWT：无状态、吊销难度大、声明灵活

Pagination

分页机制

  • Offset/limit: Simple, inconsistent under writes
  • Cursor-based: Consistent, opaque, harder to jump to page N
  • Keyset: Efficient, requires indexed sort key
  • 偏移/限制：简单、数据写入时结果不一致
  • 基于游标：结果一致、游标不透明、难以直接跳转到第N页
  • 基于键集：高效、需要排序键索引

Error Handling

错误处理

  • Problem Details (RFC 7807): Structured, extensible, standard
  • Custom format: Tailored to domain, non-standard
  • HTTP status only: Simple, lacks detail
  • 问题详情（RFC 7807）：结构化、可扩展、标准化
  • 自定义格式：贴合业务领域、非标准化
  • 仅HTTP状态码：简单、缺乏详细信息

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
workspace/
├── api-context.md                  # 阶段1：上下文收集文档
├── 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            # 最终交付物

Coordinator Responsibilities

统筹Agent职责

  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
  1. 收集上下文信息并与用户澄清需求
  2. 并行启动方案提议Agent
  3. 统筹关键设计决策的辩论
  4. 确保所有Agent参与（而非仅API Designer）
  5. 整合最终规范文档并附上设计理由
  6. 向用户提交交付物
  7. 若用户请求，可提供客户端SDK或模拟服务器生成服务

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.
用户可通过以下方式自定义研讨会：
  • 跳过特定Agent："跳过性能Agent，重点关注安全性"
  • 添加约束条件："必须支持GraphQL subscriptions"
  • 指定API风格："设计遵循JSON:API规范的REST API"
  • 设置优先级："优先优化开发者体验而非效率"
  • 提供参考示例："类似Stripe的API"或"这是我们现有的API"
  • 请求特定辩论："辩论我们是否真的需要版本控制"
根据用户需求调整Agent角色列表与辩论议题。

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.
/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
研讨会会根据用户需求自动适配，无论是设计新API、评审现有API还是对比不同方案。