ring%3apre-dev-api-design（ring 3apre DEV API 设计）

API/Contract Design - Defining Component Interfaces

Foundational Principle

Component contracts and interfaces must be defined before technology/protocol selection.

Jumping to implementation without contract definition creates:

• Integration failures discovered during development
• Inconsistent data structures across components
• Teams blocked waiting for interface clarity
• Rework when assumptions about contracts differ

The API Design answers: WHAT data/operations components expose and consume? The API Design never answers: HOW those are implemented (protocols, serialization, specific tech).

Phase 0: API Standards Discovery (MANDATORY)

Before defining contracts, check for organizational naming standards.

See shared-patterns/standards-discovery.md for complete workflow.

Context: API field naming standards Output: docs/pre-dev/{feature-name}/api-standards-ref.md

Use AskUserQuestion tool:

Question: "Do you have a data dictionary or API field naming standards to reference?"

• Header: "API Standards"
• multiSelect: false
• Options:

- "No - Use industry best practices" (description: "Generate contracts using standard naming conventions") - "Yes - URL to document" (description: "Provide a URL to your data dictionary or standards document") - "Yes - File path" (description: "Provide a local file path (.md,.json,.yaml,.csv)")

If "Yes" Selected:

1. Load the document:

2. Extract standards:

MUST extract these elements if present:

3. Save extracted standards:

Output to: docs/pre-dev/{feature-name}/api-standards-ref.md

Format:

# API Standards Reference - {Feature Name}

Source: {URL or file path}
Extracted: {timestamp}

## Field Naming Conventions
- IDs: `{pattern}` (example)
- Timestamps: `{pattern}` (example)
- Booleans: `{pattern}` (example)
- Collections: `{pattern}` (example)

## Standard Fields
| Field | Type | Format | Validation | Example |
|-------|------|--------|------------|---------|
| userId | string | UUID v4 | Required, unique | "550e8400-e29b-41d4-a716-446655440000" |
| email | string | RFC 5322 | Required, unique | "user@example.com" |
| createdAt | string | ISO 8601 | Auto-generated | "2026-01-23T10:30:00Z" |

## Standard Error Codes
| Code | Usage | HTTP Equivalent (for reference) |
|------|-------|--------------------------------|
| EMAIL_ALREADY_EXISTS | Duplicate email registration | 409 Conflict |
| INVALID_INPUT | Validation failure | 400 Bad Request |

## Validation Patterns
| Pattern Type | Rule | Example |
|-------------|------|---------|
| Email | RFC 5322, max 254 chars | "user@example.com" |
| Phone | E.164 format | "+5511987654321" |

## Pagination Standards
| Field | Type | Description |
|-------|------|-------------|
| page | integer | 1-indexed page number (offset-based) |
| limit | integer | Items per page (max 100) |
| next_cursor | string | Base64-encoded cursor for next page (cursor-based) |
| prev_cursor | string | Base64-encoded cursor for previous page (cursor-based) |

4. Apply throughout Gate 4:

• Use standard field names in operation definitions
• Reference validation patterns in contract constraints
• Apply naming conventions consistently
• Note any justified deviations with rationale

If Dictionary Conflicts with Existing Codebase:

If Phase 0 from Gate 0 (Research) found existing patterns that conflict with the dictionary:

STOP and use AskUserQuestion:

Question: "Dictionary says {dictionary_pattern}, but codebase uses {codebase_pattern}. Which should we follow?"

• Header: "Standards Conflict"
• multiSelect: false
• Options:

- "Follow dictionary" (description: "Use organizational standards, refactor existing code later") - "Follow codebase" (description: "Maintain consistency with existing implementation") - "Hybrid approach" (description: "Let me decide per-field")

If "No" Selected (Industry Best Practices):

Proceed with standard naming conventions:

• camelCase for field names (JavaScript/TypeScript)
• snake_case for field names (Python/Ruby/SQL)
• ISO 8601 for timestamps
• UUID v4 for identifiers
• RFC 5322 for emails

Document the choice in api-standards-ref.md with rationale.

Mandatory Workflow

Explicit Rules

✅ DO Include

Operation names/descriptions, input parameters (name, type, required/optional, constraints), output structure (fields, types, nullable), error codes/descriptions, event types/payloads, validation rules, idempotency requirements, auth/authz needs (abstract), versioning strategy

❌ NEVER Include

HTTP verbs (GET/POST/PUT), gRPC/GraphQL/WebSocket details, URL paths/routes, serialization formats (JSON/Protobuf), framework code, database queries, infrastructure, specific auth libraries

Abstraction Rules

Rationalization Table

Red Flags - STOP

If you catch yourself writing any of these in API Design, STOP:

• HTTP methods (GET, POST, PUT, DELETE, PATCH)
• URL paths (/api/v1/users, /users/{id})
• Protocol names (REST, GraphQL, gRPC, WebSocket)
• Status codes (200, 404, 500)
• Serialization formats (JSON, XML, Protobuf)
• Authentication tokens (JWT, OAuth2 tokens, API keys)
• Framework code (Express routes, gRPC service definitions)
• Transport mechanisms (HTTP/2, TCP, UDP)

When you catch yourself: Replace protocol detail with abstract contract. "POST /users" → "CreateUser operation"

Gate 4 Validation Checklist

Gate Result: ✅ PASS (all checked) → Data Modeling | ⚠️ CONDITIONAL (remove protocol details) | ❌ FAIL (incomplete)

Contract Template Structure

Output to (path depends on topology.structure):

• single-repo: docs/pre-dev/{feature-name}/api-design.md
• monorepo/multi-repo: {backend.path}/docs/pre-dev/{feature-name}/api-design.md

Per-Operation Structure

Event Contract Structure

Additional Sections

Common Violations

Confidence Scoring

Action: 80+ autonomous generation | 50-79 present options | <50 ask clarifying questions

Document Placement

api-design.md is a backend document - it defines API contracts implemented by backend services.

Why backend path? API contracts are:

• Implemented by backend engineers
• Referenced during backend code review
• Versioned with backend code

Directory creation for multi-module:

# Read topology from research.md frontmatter
backend_path="${topology_modules_backend_path:-"."}"
mkdir -p "${backend_path}/docs/pre-dev/{feature}"

BFF Contract Design (Frontend-only and Fullstack with BFF)

⛔ HARD GATE: If api_pattern: bff (from research.md), this section is MANDATORY.

When This Applies

Check research.md frontmatter:

topology:
  scope: frontend-only | fullstack
  api_pattern: bff  # ← This triggers BFF contract design

Phase 3: BFF Contract Definition

After backend contracts (Phase 2), define BFF-to-Frontend contracts:

BFF Contract Template

Add to api-design.md under ## BFF Contracts section:

## BFF Contracts

### Overview
- **Pattern:** BFF (Backend-for-Frontend)
- **Purpose:** [Aggregation | Transformation | Security | All]
- **Frontend Framework:** [Next.js | React | Vue | etc.]

### BFF Operations

#### Operation: Get{Feature}Data

**Purpose:** Aggregate data for {feature} component

**Frontend Consumer:** `{ComponentName}.tsx`

**Backend APIs Consumed:**
| API | Operation | Purpose |
|-----|-----------|---------|
| User Service | GetUser | User profile data |
| Order Service | ListOrders | Recent orders |

**Input Contract:**
| Parameter | Type | Required | Constraints | Description |
|-----------|------|----------|-------------|-------------|
| userId | Identifier | Yes | Valid UUID | Target user |
| limit | Integer | No | 1-100, default 10 | Max orders |

**Output Contract (Frontend-Optimized):**
| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| user | UserSummary | No | Simplified user object |
| user.id | Identifier | No | User ID |
| user.displayName | String | No | Formatted name |
| recentOrders | OrderSummary[] | No | Last N orders |
| recentOrders[].id | Identifier | No | Order ID |
| recentOrders[].total | FormattedCurrency | No | Display-ready total |

**Error Normalization:**
| Backend Error | BFF Error Code | Frontend Action |
|---------------|----------------|-----------------|
| User 404 | USER_NOT_FOUND | Redirect to error page |
| Orders 500 | ORDERS_UNAVAILABLE | Show partial data |
| Auth 401 | SESSION_EXPIRED | Trigger re-auth |

Type Transformation Rules

BFF MUST transform backend types to frontend-optimized types:

Frontend-only Specific Requirements

If topology.scope: frontend-only:

The BFF consumes EXISTING backend APIs (documented in PRD Data Sources).

MUST verify:

1. All PRD Data Sources are covered by BFF operations
2. All API gaps identified in PRD have corresponding BFF operations
3. BFF operations match frontend component data needs

### PRD Data Source Coverage

| PRD Data Source | Covered by BFF Operation | Notes |
|-----------------|-------------------------|-------|
| User API | GetDashboardData | User summary included |
| Orders API | GetDashboardData | Recent orders included |
| Reports API | GenerateReport | New BFF operation |

Gate 4 Validation Addition for BFF

Rationalization Table for BFF Contracts

After Approval

1. ✅ Lock contracts - interfaces are now implementation reference
2. 🎯 Use contracts as input for Data Modeling (ring:pre-dev-data-model)
3. 🚫 Never add protocol specifics retroactively
4. 📋 Keep technology-agnostic until Dependency Map

The Bottom Line

If you wrote API contracts with HTTP endpoints or gRPC services, remove them.

Contracts are protocol-agnostic. Period. No REST. No GraphQL. No HTTP codes.

Protocol choices go in Dependency Map. That's a later phase. Wait for it.

Define the contract. Stay abstract. Choose protocol later.

Standards Loading (MANDATORY)

This skill is an API contract design skill and does NOT require WebFetch of language-specific standards.

Purpose: API Design defines WHAT operations and data contracts exist, not HOW they're implemented. Protocol-specific patterns apply during Dependency Map (Gate 6) and implementation.

However, MUST complete Phase 0 (API Standards Discovery) to check for organizational naming standards before designing contracts.

Blocker Criteria - STOP and Report

Cannot Be Overridden

These requirements are NON-NEGOTIABLE:

• MUST NOT include HTTP verbs (GET, POST, PUT, DELETE)
• MUST NOT include URL paths (/api/v1/users, etc.)
• MUST NOT include protocol names (REST, GraphQL, gRPC)
• MUST NOT include HTTP status codes (200, 404, 500)
• MUST complete Phase 0 (API Standards Discovery) before designing
• MUST define error contracts for all operations
• MUST define BFF contracts if api_pattern is bff
• CANNOT proceed to Gate 5 with protocol-specific content

Severity Calibration

Pressure Resistance

When This Skill Is Not Needed

• Small Track workflow (skip to Task Breakdown)
• Single component system (skip to Data Model)
• TRD (Gate 3) not validated (complete Gate 3 first)
• API Design already exists and is validated
• No component-to-component communication needed
• Pure frontend feature with no API changes