ringpre-dev-api-design

name	ring:pre-dev-api-design
description	Gate 4: API contracts document - defines component interfaces and data contracts before protocol/technology selection. Large Track only.
license	MIT
compatibility	opencode
metadata	{"trigger":"- TRD passed Gate 3 validation\n- System has multiple components that need to integrate\n- Building APIs (internal or external)\n- Large Track workflow (2+ day features)\n","skip_when":"- Small Track workflow → skip to Task Breakdown\n- Single component system → skip to Data Model\n- TRD not validated → complete Gate 3 first\n"}
sequence	{"after":["ring:pre-dev-trd-creation"],"before":["ring:pre-dev-data-model"]}

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:

Source Type	Tool	Actions
URL	WebFetch	Fetch document content; parse for field definitions, naming rules, validation patterns
File path	Read	Read file content; support .md (Markdown tables), .json (structured), .yaml (structured), .csv (tabular)

2. Extract standards:

MUST extract these elements if present:

Element	What to Extract	Example
Field naming convention	camelCase, snake_case, PascalCase	userId vs user_id
Standard field names	Common fields used across APIs	createdAt, updatedAt, isActive
Data type formats	How to represent dates, IDs, amounts	ISO8601, UUID v4, Decimal(10,2)
Validation patterns	Regex, constraints, rules	Email RFC 5322, phone E.164
Standard error codes	Organizational error naming	EMAIL_ALREADY_EXISTS vs DuplicateEmail
Pagination fields	Standard query/response pagination	page, pageSize, totalCount

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 | "[e-mail]" |
| 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 | "[e-mail]" |
| Phone | E.164 format | "[phone]" |

## Pagination Standards
| Field | Type | Description |
|-------|------|-------------|
| page | integer | 1-indexed page number |
| pageSize | integer | Items per page (max 100) |
| totalCount | integer | Total items across all pages |

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

Phase	Activities
0. API Standards Discovery	Check for organizational field naming standards (data dictionary); load from URL or file if provided; extract field conventions, types, validation patterns; save to api-standards-ref.md for reference throughout gate
1. Contract Analysis	Load approved TRD (Gate 3), Feature Map (Gate 2), PRD (Gate 1); identify integration points from TRD component diagram; extract data flows
2. Contract Definition	Per interface: define operations, specify inputs/outputs, define errors, document events, set constraints (validation), version contracts; apply standards from Phase 0 if available
3. Gate 4 Validation	Verify all checkboxes in validation checklist before proceeding to Data Modeling

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

Element	Abstract (✅)	Protocol-Specific (❌)
Operation	"CreateUser"	"POST /api/v1/users"
Data Type	"EmailAddress (validated)"	"string with regex"
Error	"UserAlreadyExists"	"HTTP 409 Conflict"
Auth	"Requires authenticated user"	"JWT Bearer token"
Format	"ISO8601 timestamp"	"time.RFC3339"

Rationalization Table

Excuse	Reality
"No need to ask about data dictionary"	Organizations have standards. Check first, don't assume. Phase 0 is MANDATORY.
"I'll just use common sense for field names"	"Common sense" varies. Ask for standards, or explicitly choose best practices.
"Skip Phase 0, user will mention standards if important"	User doesn't know when to mention it. YOU must ask proactively.
"REST is obvious, just document endpoints"	Protocol choice goes in Dependency Map. Define contracts abstractly.
"We need HTTP codes for errors"	Error semantics matter; HTTP codes are protocol. Abstract the errors.
"Teams need to see JSON examples"	JSON is serialization. Define structure; format comes later.
"The contract IS the OpenAPI spec"	OpenAPI is protocol-specific. Design contracts first, generate specs later.
"gRPC/GraphQL affects the contract"	Protocols deliver contracts. Design protocol-agnostic contracts first.
"We already know it's REST"	Knowing doesn't mean documenting prematurely. Stay abstract.
"Framework validates inputs"	Validation logic is universal. Document rules; implementation comes later.
"This feels redundant with TRD"	TRD = components exist. API = how they talk. Different concerns.
"URL structure matters for APIs"	URLs are HTTP-specific. Focus on operations and data.
"But API Design means REST API"	API = interface. Could be REST, gRPC, events, or in-process. Stay abstract.

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

Category	Requirements
Contract Completeness	All component-to-component interactions have contracts; all external integrations covered; all event/message contracts defined; client-facing APIs specified
Operation Clarity	Each operation has clear purpose/description; consistent naming convention; idempotency documented; batch operations identified
Data Specification	All inputs typed and documented; required vs optional explicit; outputs complete; null/empty cases handled
Error Handling	All scenarios identified; error codes/types defined; actionable messages; retry/recovery documented
Event Contracts	All events named/described; payloads specified; ordering/delivery semantics documented; versioning defined
Constraints & Policies	Validation rules explicit; timeouts specified; backward compatibility exists
Technology Agnostic	No protocol specifics; no serialization formats; no framework names; implementable in any protocol

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

Section	Content
Overview	TRD/Feature Map/PRD references, status, last updated
Versioning Strategy	Approach (semantic/date-based), backward compatibility policy, deprecation process
Component Contracts	Per component: purpose, integration points (inbound/outbound), operations

Per-Operation Structure

Field	Content
Purpose	What the operation does
Inputs	Table: Parameter, Type, Required, Constraints, Description
Validation Rules	Format patterns, business rules
Outputs (Success)	Table: Field, Type, Nullable, Description + abstract structure
Errors	Table: Error Code, Condition, Description, Retry?
Idempotency	Behavior on duplicate calls
Authorization	Required permissions (abstract)
Related Operations	Events triggered, downstream calls

Event Contract Structure

Field	Content
Purpose/When Emitted	Trigger conditions
Payload	Table: Field, Type, Nullable, Description
Consumers	Services that consume this event
Delivery Semantics	At-least-once, at-most-once, exactly-once
Ordering/Retention	Ordering guarantees, retention period

Additional Sections

Section	Content
Cross-Component Integration	Per integration: purpose, operations used, data flow diagram (abstract), error handling
External System Contracts	Operations exposed to us, operations we expose, per-operation details
Custom Type Definitions	Per type: base type, format, constraints, example
Naming Conventions	Operations (verb+noun), parameters (camelCase), events (past tense), errors (noun+condition)
Backward Compatibility	Breaking vs non-breaking changes, deprecation timeline
Testing Contracts	Contract testing strategy, example test scenarios
Gate 4 Validation	Date, validator, checklist, approval status

Common Violations

Violation	Wrong	Correct
Protocol Details	"Endpoint: POST /api/v1/users, Status: 201 Created, 409 Conflict"	"Operation: CreateUser, Errors: EmailAlreadyExists, InvalidInput"
Implementation Code	JavaScript regex validation code	"email must match RFC 5322 format, max 254 chars"
Technology Types	JSON example with "uuid", "Date", "Map<String,Any>"	Table with abstract types: Identifier (UUID format), Timestamp (ISO8601), ProfileObject

Confidence Scoring

Factor	Points	Criteria
Contract Completeness	0-30	All ops: 30, Most: 20, Gaps: 10
Interface Clarity	0-25	Clear/unambiguous: 25, Some interpretation: 15, Vague: 5
Integration Complexity	0-25	Simple point-to-point: 25, Moderate deps: 15, Complex orchestration: 5
Error Handling	0-20	All scenarios: 20, Common cases: 12, Minimal: 5

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.

Structure	api-design.md Location
single-repo	docs/pre-dev/{feature}/api-design.md
monorepo	{backend.path}/docs/pre-dev/{feature}/api-design.md
multi-repo	{backend.path}/docs/pre-dev/{feature}/api-design.md

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:

Step	Activity
1	Identify all frontend components that need data
2	Map component data needs to backend APIs
3	Define BFF aggregation operations
4	Specify BFF response contracts (frontend-optimized shapes)
5	Document error normalization strategy

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:

Backend Type	Frontend Type	Transformation
ISO8601 string	RelativeTime	"2 hours ago"
Decimal amount	FormattedCurrency	"$1,234.56"
Full entity	Summary object	Select display fields
Nested IDs	Resolved names	Join data

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

Category	Requirements
BFF Completeness	All frontend components have data contracts; all backend APIs mapped to BFF operations; error normalization defined; type transformations documented

Rationalization Table for BFF Contracts

Excuse	Reality
"BFF is just a proxy"	Proxies still transform errors and aggregate. Document contracts.
"Frontend types are implementation"	Types define component contracts. Design them here.
"We'll figure out transformations later"	Later = bugs. Define transformations upfront.
"Backend contract = frontend contract"	Backend serves multiple clients. Frontend needs optimized shapes.
"BFF contracts are obvious from UI"	Obvious to you ≠ documented. Write explicit 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.