Design API Stories

Design API Stories

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.

When to Use

Use when the user says /design-api-stories or asks to generate API user stories from requirements.

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.

1. Requirements — ICP, needs, pain points, use cases, benefits. The "why" and "what." Look for a heading like # Requirements, # Research, or similar.
2. Domain — Data objects, properties, enums, object relations. The "nouns." Look for a heading like # Domain, # Domain Model, or similar.
3. 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.

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

Step 1: Read All Inputs

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)

Step 2: Identify Themes and Use Cases

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.

Step 3: Generate Stories (Default = Simple)

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

Simple Story Format (default)

For each story, output ONLY:

#### 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

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

Step 4: Present for Review

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

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

1. 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."

2. 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.

3. 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.

4. 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.

5. 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.

6. Pagination follows standards. If standards specify cursor-based pagination, every collection endpoint gets cursor and limit parameters. Don't mix pagination styles.

Example Output (Simple)

# Pet Store API: User Stories

## Theme 1: Pet Management

#### Story 1.1: List Pets

**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).

#### Story 1.2: Get Pet Details

**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.