design-api-stories

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design API Stories

API设计故事生成

Generate API design stories from requirements, a domain model, and API standards. This is Emmanuel Paraskakis's method for designing APIs with LLMs — the stories become the bridge between product requirements and an OpenAPI specification.

根据需求、领域模型和API标准生成API设计故事。这是Emmanuel Paraskakis提出的使用LLM设计API的方法——这些故事是产品需求与OpenAPI规范之间的桥梁。

When to Use

使用场景

Use when the user says

/design-api-stories

or asks to generate API user stories from requirements.

当用户输入“/design-api-stories”或要求根据需求生成API用户故事时使用。

Inputs

输入要求

The user must provide three files (or paste their content). Files can be named anything — identify each file by its

# Title

heading or content, not by filename.

Requirements — ICP, needs, pain points, use cases, benefits. The "why" and "what." Look for a heading like
```
# Requirements
```
,
```
# Research
```
, or similar.
Domain — Data objects, properties, enums, object relations. The "nouns." Look for a heading like
```
# Domain
```
,
```
# Domain Model
```
, or similar.
API Standards — Style guide, naming conventions, path rules, security, error handling. The "how." Look for a heading like
```
# API Standards
```
,
```
# Style Guide
```
, or similar.

If any file is missing, ask the user to provide it before proceeding.

用户必须提供三个文件（或粘贴其内容）。文件名可以任意——通过文件的

# 标题

或内容识别每个文件，而非文件名。

需求文档 — 包含理想客户画像（ICP）、需求、痛点、用例、收益。即API的“原因”和“内容”。寻找类似
```
# Requirements
```
、
```
# Research
```
的标题。
领域模型 — 包含数据对象、属性、枚举、对象关系。即API的“名词”。寻找类似
```
# Domain
```
、
```
# Domain Model
```
的标题。
API标准 — 包含风格指南、命名规范、路径规则、安全机制、错误处理。即API的“实现方式”。寻找类似
```
# API Standards
```
、
```
# Style Guide
```
的标题。

如果缺少任何文件，请在继续之前要求用户提供。

Working Example

示例参考

See

references/examples/

for a complete set of inputs (conference scheduling API):

```
conference-research.md
```
— requirements
```
conference-domain.md
```
— domain model
```
API-standards.md
```
— API standards

查看

references/examples/

获取完整的输入示例（会议调度API）：

```
conference-research.md
```
— 需求文档
```
conference-domain.md
```
— 领域模型
```
API-standards.md
```
— API标准

Step 1: Read All Inputs

步骤1：读取所有输入

Read all three files completely. Understand:

Who the API consumers are (from requirements)
What entities and relationships exist (from domain)
What conventions to follow (from standards)

完整读取三个文件，理解：

API的使用者是谁（来自需求文档）
存在哪些实体和关系（来自领域模型）
需要遵循哪些规范（来自API标准）

Step 2: Identify Themes and Use Cases

步骤2：识别主题与用例

Group the use cases from the requirements into logical themes. Each theme maps to a cluster of related API operations. Do not pause here — proceed immediately to Step 3 and generate all stories.

Exception: if the user explicitly asks for step-by-step review, present the themes first and wait for confirmation.

将需求文档中的用例分组为逻辑主题。每个主题对应一组相关的API操作。请勿在此处暂停——立即进入步骤3并生成所有故事。

例外情况：如果用户明确要求分步审核，请先展示主题并等待确认。

Step 3: Generate Stories (Default = Simple)

步骤3：生成故事（默认=简洁版）

By default, generate simple stories — just enough for a product manager to review the API shape and validate the design direction.

默认生成简洁版故事——仅需足够让产品经理审核API形态并验证设计方向的内容。

Simple Story Format (default)

简洁版故事格式（默认）

For each story, output ONLY:

undefined

每个故事仅输出以下内容：

undefined

Story [Theme].[Number]: [Name]

As a [actor from requirements], I want to [action], So that [business value].

Method:
```
GET
```
/
```
POST
```
/
```
PUT
```
/
```
PATCH
```
/
```
DELETE
```
Resource:
```
/path/{id}/subresource
```
Parameters:
- ```
paramName
```
  (type, required/optional): Brief description.


Rules for simple stories:
- Method and resource MUST follow the API standards (naming, nesting, pluralization)
- Parameters include path params, query params, and request body fields
- Mark each parameter as required or optional
- Use domain object names and property names exactly as defined
- Do NOT include response schemas, error codes, headers, or implementation details
- Do NOT include authentication details unless the standards specify something unusual

As a [actor from requirements], I want to [action], So that [business value].

Method:
```
GET
```
/
```
POST
```
/
```
PUT
```
/
```
PATCH
```
/
```
DELETE
```
Resource:
```
/path/{id}/subresource
```
Parameters:
- ```
paramName
```
  (type, required/optional): Brief description.


简洁版故事规则：
- 请求方法和资源路径必须遵循API标准（命名、嵌套、复数形式）
- 参数包括路径参数、查询参数和请求体字段
- 标记每个参数为必填或可选
- 严格使用领域模型中定义的对象名称和属性名称
- 请勿包含响应 schema、错误码、请求头或实现细节
- 除非标准中有特殊规定，否则请勿包含认证细节

Detailed Story Format (on request)

详细版故事格式（按需生成）

If the user asks for detailed stories (e.g.,

/design-api-stories --detailed

), add:

Success response summary (status code + what's returned)
Error responses (status codes + when they occur)
Headers (rate limiting, pagination cursors)
Notes on pagination approach

如果用户要求生成详细版故事（例如：

/design-api-stories --detailed

），添加以下内容：

成功响应摘要（状态码 + 返回内容说明）
错误响应（状态码 + 触发场景）
请求头（限流、分页游标）
分页方式说明

Step 4: Present for Review

步骤4：提交审核

Present all themes and stories in a single pass. Do not pause between themes or ask for confirmation after each one — deliver the complete output, then ask once at the end if anything needs to change.

Exception: if the user explicitly asks for step-by-step review, pause after each theme.

一次性展示所有主题和故事。请勿在主题之间暂停或在每个故事后请求确认——输出完整内容后，仅在末尾询问是否需要修改。

例外情况：如果用户明确要求分步审核，请在每个主题后暂停。

Step 5: Save

步骤5：保存

Save the completed stories to a file the user specifies, or ask where they'd like it saved. No specific naming convention required.

Write directly — do not check for or read existing files first. If the Write tool fails due to a name conflict, append a number and try again.

将完成的故事保存到用户指定的文件中，或询问用户保存位置。无特定命名规范要求。

直接写入——无需先检查或读取现有文件。 如果写入工具因名称冲突失败，追加数字后重试。

Key Principles

核心原则

Stories are for PM review, not engineering specs. Keep them scannable. A PM should be able to look at the method + resource + parameters and say "yes, that's the right API" or "no, we're missing X."
Follow the standards religiously. If the standards say camelCase, every parameter is camelCase. If they say pluralized resources, every resource is plural. If they say no /api prefix, don't add one. The stories ARE the first enforcement of the standards.
Use domain language exactly. If the domain says
```
exchangeMic
```
, the parameter is
```
exchangeMic
```
, not
```
exchange_mic
```
or
```
exchangeId
```
. Domain is the source of truth for naming.
Nest resources per the domain relations. If a Quote belongs to an Instrument, the resource is
```
/instruments/{id}/quotes
```
, not
```
/quotes?instrumentId=X
```
. Follow the nesting depth limit from standards.
Don't invent requirements. If the requirements don't mention delete or update operations, don't add them. Only design what was asked for. If you think something is missing, flag it as a question, don't silently add it.
Pagination follows standards. If standards specify cursor-based pagination, every collection endpoint gets
```
cursor
```
and
```
limit
```
parameters. Don't mix pagination styles.

故事用于产品经理审核，而非工程规范。 保持内容易读。产品经理只需查看请求方法 + 资源路径 + 参数就能判断“这是正确的API”或“不，我们遗漏了X”。
严格遵循标准。 如果标准要求使用驼峰式（camelCase），所有参数都必须用驼峰式；如果要求资源使用复数形式，所有资源都必须是复数；如果要求不添加
```
/api
```
前缀，就不要添加。故事是标准的首次落地执行。
严格使用领域术语。 如果领域模型中是
```
exchangeMic
```
，参数就必须是
```
exchangeMic
```
，而非
```
exchange_mic
```
或
```
exchangeId
```
。领域模型是命名的唯一来源。
根据领域关系嵌套资源。 如果Quote属于Instrument，资源路径应为
```
/instruments/{id}/quotes
```
，而非
```
/quotes?instrumentId=X
```
。遵循标准中规定的嵌套深度限制。
不要凭空添加需求。 如果需求文档未提及删除或更新操作，不要添加。仅设计要求的内容。如果认为有遗漏，标记为问题，不要擅自添加。
分页遵循标准。 如果标准指定基于游标的分页，所有集合端点都要添加
```
cursor
```
和
```
limit
```
参数。不要混合分页方式。

Example Output (Simple)

示例输出（简洁版）

markdown

undefined

markdown

undefined

Pet Store API: User Stories

宠物商店API：用户故事

Theme 1: Pet Management

主题1：宠物管理

Story 1.1: List Pets

故事1.1：列出宠物

As a store employee, I want to browse all pets with optional filters, So that I can find pets matching a customer's preferences.

Method:
```
GET
```
Resource:
```
/pets
```
Parameters:
- ```
cursor
```
  (string, optional): Pagination cursor.
- ```
limit
```
  (integer, optional): Max results. Default 20.
- ```
species
```
  (enum, optional): Filter by species (Dog, Cat, Bird, Fish).
- ```
status
```
  (enum, optional): Filter by availability (Available, Sold, Pending).

作为商店员工， 我希望 可以通过可选筛选条件浏览所有宠物，以便找到符合客户偏好的宠物。

请求方法:
```
GET
```
资源路径:
```
/pets
```
参数:
- ```
cursor
```
  (字符串, 可选): 分页游标。
- ```
limit
```
  (整数, 可选): 最大结果数。默认值为20。
- ```
species
```
  (枚举, 可选): 按物种筛选（Dog、Cat、Bird、Fish）。
- ```
status
```
  (枚举, 可选): 按可用状态筛选（Available、Sold、Pending）。

Story 1.2: Get Pet Details

故事1.2：查看宠物详情

As a store employee, I want to view full details of a specific pet, So that I can answer customer questions about the pet.

Method:
```
GET
```
Resource:
```
/pets/{petId}
```
Parameters:
- ```
petId
```
  (string, required): Unique pet identifier.

undefined

作为商店员工， 我希望 查看特定宠物的完整详情，以便回答客户关于该宠物的问题。

请求方法:
```
GET
```
资源路径:
```
/pets/{petId}
```
参数:
- ```
petId
```
  (字符串, 必填): 宠物唯一标识符。

undefined