---
name: pre-dev-api-design
description: |
  Gate 4: API contracts document - defines component interfaces and data contracts
  before protocol/technology selection. Large Track only.

trigger: |
  - TRD passed Gate 3 validation
  - System has multiple components that need to integrate
  - Building APIs (internal or external)
  - Large Track workflow (2+ day features)

skip_when: |
  - Small Track workflow → skip to Task Breakdown
  - Single component system → skip to Data Model
  - TRD not validated → complete Gate 3 first

sequence:
  after: [pre-dev-trd-creation]
  before: [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
- No clear integration test boundaries

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

## When to Use This Skill

Use this skill when:
- TRD has passed Gate 3 validation
- System has multiple components that need to integrate
- Building APIs (internal or external)
- Microservices, modular monoliths, or distributed systems
- Need clear contracts for parallel development

## Mandatory Workflow

### Phase 1: Contract Analysis (Inputs Required)
1. **Approved TRD** (Gate 3 passed) - architecture patterns defined
2. **Approved Feature Map** (Gate 2 passed) - feature interactions mapped
3. **Approved PRD** (Gate 1 passed) - business requirements locked
4. **Identify integration points** from TRD component diagram
5. **Extract data flows** from Feature Map

### Phase 2: Contract Definition
For each component interface:
1. **Define operations** (what actions can be performed)
2. **Specify inputs** (what data is required)
3. **Specify outputs** (what data is returned)
4. **Define errors** (what failure cases exist)
5. **Document events** (what notifications are sent)
6. **Set constraints** (validation rules, rate limits)
7. **Version contracts** (how changes are managed)

### Phase 3: Gate 4 Validation
**MANDATORY CHECKPOINT** - Must pass before proceeding to Data Modeling:
- [ ] All TRD component interactions have contracts
- [ ] Operations are clearly named and described
- [ ] Inputs/outputs are fully specified
- [ ] Error scenarios are documented
- [ ] Events are defined with schemas
- [ ] Constraints are explicit (validation, limits)
- [ ] Versioning strategy is defined
- [ ] No protocol specifics (REST/gRPC/GraphQL)
- [ ] No technology implementations

## Explicit Rules

### ✅ DO Include in API Design
- Operation names and descriptions
- Input parameters (name, type, required/optional, constraints)
- Output structure (fields, types, nullable)
- Error codes and descriptions
- Event types and payloads
- Validation rules (format, ranges, patterns)
- Rate limits or quota policies
- Idempotency requirements
- Authentication/authorization needs (abstract)
- Contract versioning strategy

### ❌ NEVER Include in API Design
- HTTP verbs (GET/POST/PUT) or REST specifics
- gRPC/GraphQL/WebSocket protocol details
- URL paths or route definitions
- Serialization formats (JSON/Protobuf/Avro)
- Framework-specific code (middleware, decorators)
- Database queries or ORM code
- Infrastructure (load balancers, API gateways)
- Specific authentication libraries (JWT libraries, OAuth packages)

### Abstraction Rules
1. **Operation**: Say "CreateUser" not "POST /api/v1/users"
2. **Data Type**: Say "EmailAddress (validated)" not "string with regex"
3. **Error**: Say "UserAlreadyExists" not "HTTP 409 Conflict"
4. **Auth**: Say "Requires authenticated user" not "JWT Bearer token"
5. **Format**: Say "ISO8601 timestamp" not "time.RFC3339"

## Rationalization Table

| Excuse | Reality |
|--------|---------|
| "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

Before proceeding to Data Modeling, verify:

**Contract Completeness**:
- [ ] All component-to-component interactions have contracts
- [ ] All external system integrations have contracts
- [ ] All event/message contracts are defined
- [ ] Client-facing APIs are fully specified

**Operation Clarity**:
- [ ] Each operation has clear purpose and description
- [ ] Operation names follow consistent naming convention
- [ ] Idempotency requirements are documented
- [ ] Batch operations are identified where relevant

**Data Specification**:
- [ ] All input parameters are typed and documented
- [ ] Required vs. optional is explicit
- [ ] Output structures are complete
- [ ] Null/empty cases are handled

**Error Handling**:
- [ ] All error scenarios are identified
- [ ] Error codes/types are defined
- [ ] Error messages provide actionable guidance
- [ ] Retry/recovery strategies are documented

**Event Contracts**:
- [ ] All events are named and described
- [ ] Event payloads are fully specified
- [ ] Event ordering/delivery semantics documented
- [ ] Event versioning strategy defined

**Constraints & Policies**:
- [ ] Validation rules are explicit (format, range, pattern)
- [ ] Rate limits or quotas are defined
- [ ] Timeouts and deadlines are specified
- [ ] Backward compatibility strategy exists

**Technology Agnostic**:
- [ ] No protocol-specific details (REST/gRPC/etc)
- [ ] No serialization format specifics
- [ ] No framework or library names
- [ ] Can implement in any protocol

**Gate Result**:
- ✅ **PASS**: All checkboxes checked → Proceed to Data Modeling
- ⚠️ **CONDITIONAL**: Remove protocol details → Re-validate
- ❌ **FAIL**: Incomplete contracts → Add missing specifications

## Contract Template

```markdown
# API/Contract Design: [Project/Feature Name]

## Overview
- **TRD Reference**: [Link to approved TRD]
- **Feature Map Reference**: [Link to approved Feature Map]
- **Last Updated**: [Date]
- **Status**: Draft / Under Review / Approved

## Contract Versioning Strategy
- **Approach**: [e.g., Semantic versioning, Date-based, etc.]
- **Backward Compatibility**: [Policy for breaking changes]
- **Deprecation Process**: [How old contracts are sunset]

## Component Contracts

### Component: [Component Name]
**Purpose**: [What this component does - from TRD]

**Integration Points** (from TRD):
- Inbound: [Components that call this one]
- Outbound: [Components this one calls]

---

#### Operation: [OperationName]

**Purpose**: [What this operation does]

**Inputs**:
| Parameter | Type | Required | Constraints | Description |
|-----------|------|----------|-------------|-------------|
| userId | Identifier | Yes | Non-empty, UUID format | Unique user identifier |
| email | EmailAddress | Yes | Valid email format | User's email address |
| displayName | String | No | 3-50 chars, alphanumeric | Public display name |
| preferences | PreferenceSet | No | - | User preferences object |

**Input Validation Rules**:
- `email` must match pattern: `[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}`
- `displayName` must not contain profanity (filter list: [reference])
- `preferences.theme` must be one of: ["light", "dark", "auto"]

**Outputs** (Success):
| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| userId | Identifier | No | Created user's unique ID |
| createdAt | Timestamp | No | ISO8601 timestamp of creation |
| status | UserStatus | No | Account status: "active" | "pending_verification" |

**Output Structure Example** (abstract):
```
UserCreatedResponse {
  userId: Identifier
  createdAt: Timestamp
  status: UserStatus
}
```

**Errors**:
| Error Code | Condition | Description | Retry? |
|------------|-----------|-------------|--------|
| InvalidEmail | Email format invalid | Provided email doesn't match format | No |
| EmailAlreadyExists | Email in use | Account with this email exists | No |
| RateLimitExceeded | Too many requests | Max 5 creates per hour per IP | Yes, after delay |
| ServiceUnavailable | Downstream failure | Dependency unavailable | Yes, with backoff |

**Idempotency**:
- Idempotent if called with same `email` within 5 minutes
- Returns existing user if already created

**Authorization**:
- Requires: Anonymous (public operation)
- Rate limited: 5 requests per hour per IP

**Related Operations**:
- Triggers Event: `UserCreated` (see Events section)
- May call: `SendVerificationEmail` (async)

---

#### Operation: [AnotherOperationName]
[Same structure as above]

---

## Event Contracts

### Event: UserCreated

**Purpose**: Notifies system that new user account was created

**When Emitted**: After successful user creation, before returning response

**Payload**:
| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| eventId | Identifier | No | Unique event identifier |
| timestamp | Timestamp | No | ISO8601 event timestamp |
| userId | Identifier | No | Created user's ID |
| email | EmailAddress | No | User's email (for notifications) |
| source | String | No | Registration source: "web" | "mobile" | "api" |

**Payload Structure Example** (abstract):
```
UserCreatedEvent {
  eventId: Identifier
  timestamp: Timestamp
  userId: Identifier
  email: EmailAddress
  source: String
}
```

**Consumers**:
- Email Service (sends welcome email)
- Analytics Service (tracks signups)
- Audit Log Service (records event)

**Delivery Semantics**:
- At-least-once delivery
- Consumers must handle duplicates (idempotency required)

**Ordering**:
- No guaranteed ordering with other events
- Events for same `userId` are ordered

**Retention**:
- Events retained for 30 days in event store

---

### Event: [AnotherEvent]
[Same structure as above]

---

## Cross-Component Integration Contracts

### Integration: User Service → Email Service

**Purpose**: Send transactional emails to users

**Operations Used**:
- `SendEmail` (async, fire-and-forget)
- `GetEmailStatus` (query email delivery status)

**Contract Reference**: See Email Service component contracts

**Data Flow**:
```
UserService --[UserCreated event]--> EventBroker --[subscribe]--> EmailService
EmailService --[SendEmail operation]--> EmailProvider
```

**Error Handling**:
- Email Service failures do NOT block User Service operations
- Retries handled by Email Service (3 attempts, exponential backoff)
- Dead-letter queue for permanent failures

---

### Integration: [Another Integration]
[Same structure as above]

---

## External System Contracts

### External System: Payment Gateway

**Purpose**: Process payments for user subscriptions

**Operations Exposed to Us**:
- `InitiatePayment`: Start payment transaction
- `CheckPaymentStatus`: Query transaction status
- `RefundPayment`: Reverse transaction

**Operations We Expose to Them**:
- `PaymentWebhook`: Receive payment status updates

**Contract Details**:

#### Operation: InitiatePayment (We call Them)

**Inputs**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| transactionId | Identifier | Yes | Our internal transaction ID |
| amount | MonetaryAmount | Yes | Amount in smallest currency unit (cents) |
| currency | CurrencyCode | Yes | ISO 4217 code (USD, EUR, etc.) |
| customerEmail | EmailAddress | Yes | Customer's email for receipt |

**Outputs**:
| Field | Type | Description |
|-------|------|-------------|
| paymentId | Identifier | Gateway's payment ID (store for status checks) |
| redirectUrl | URL | URL to redirect user for payment |
| expiresAt | Timestamp | Payment link expiration |

**Errors**:
| Error Code | Description |
|------------|-------------|
| InvalidAmount | Amount out of acceptable range |
| UnsupportedCurrency | Currency not supported |
| GatewayUnavailable | External service down |

---

#### Operation: PaymentWebhook (They call Us)

**Purpose**: Receive async payment status updates

**Inputs**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| paymentId | Identifier | Yes | Gateway's payment ID |
| status | PaymentStatus | Yes | "succeeded" | "failed" | "pending" |
| transactionId | Identifier | Yes | Our transaction ID (from InitiatePayment) |
| timestamp | Timestamp | Yes | Status update timestamp |
| signature | String | Yes | HMAC signature for verification |

**Outputs**:
| Field | Type | Description |
|-------|------|-------------|
| acknowledged | Boolean | Always true (confirms receipt) |

**Security**:
- Must verify HMAC signature before processing
- Signature algorithm: HMAC-SHA256
- Secret key: [stored in secrets management]

**Idempotency**:
- Must handle duplicate webhooks (same paymentId + status)
- Store processed webhook IDs for deduplication

---

## Data Type Definitions

### Custom Types

#### EmailAddress
- **Base Type**: String
- **Format**: Valid email format per RFC 5322
- **Constraints**: Max 254 characters, case-insensitive
- **Example**: "user@example.com"

#### Identifier
- **Base Type**: String
- **Format**: UUID v4
- **Constraints**: Non-empty, immutable
- **Example**: "550e8400-e29b-41d4-a716-446655440000"

#### Timestamp
- **Base Type**: String
- **Format**: ISO 8601 with timezone
- **Constraints**: UTC timezone, millisecond precision
- **Example**: "2025-10-23T16:45:00.123Z"

#### MonetaryAmount
- **Base Type**: Integer
- **Format**: Amount in smallest currency unit (cents, pence, etc.)
- **Constraints**: Non-negative, max value 9,223,372,036,854,775,807
- **Example**: 1999 (represents $19.99)

#### CurrencyCode
- **Base Type**: String
- **Format**: ISO 4217 three-letter code
- **Constraints**: Uppercase, exactly 3 characters
- **Example**: "USD", "EUR", "GBP"

#### UserStatus
- **Base Type**: Enum
- **Values**: "active", "suspended", "deleted", "pending_verification"
- **Description**: Current account status

---

## Naming Conventions

**Operations**:
- Use verb + noun format: `CreateUser`, `GetPayment`, `UpdateProfile`
- Be specific: `ArchiveUser` instead of `DeleteUser` if soft-delete

**Parameters**:
- Use camelCase: `userId`, `createdAt`, `displayName`
- Be descriptive: `subscriptionExpiresAt` not `expiry`
- Boolean parameters: prefix with `is`/`has`: `isActive`, `hasPermission`

**Events**:
- Use past tense: `UserCreated`, `PaymentProcessed`, `OrderShipped`
- Include entity: `OrderShipped` not just `Shipped`

**Errors**:
- Use noun + condition: `ResourceNotFound`, `InvalidInput`, `RateLimitExceeded`
- Be specific: `EmailAlreadyExists` not `DuplicateError`

---

## Rate Limiting & Quotas

### Per-Operation Limits

| Operation | Limit | Window | Scope |
|-----------|-------|--------|-------|
| CreateUser | 5 requests | 1 hour | Per IP address |
| GetUserProfile | 100 requests | 1 minute | Per user |
| UpdateProfile | 10 requests | 1 minute | Per user |
| SendPasswordReset | 3 requests | 1 hour | Per email |

### Quota Policies
- Free tier: 1,000 API calls per day
- Pro tier: 100,000 API calls per day
- Enterprise: Custom limits

### Exceeded Limit Behavior
- Return error: `RateLimitExceeded`
- Include retry info: `retryAfter` timestamp
- Do NOT process request

---

## Backward Compatibility Strategy

### Breaking Changes
**Definition**: Changes that require consumers to update
- Removing fields from outputs
- Adding required parameters to inputs
- Changing data types
- Renaming operations

**Process**:
1. Announce deprecation 90 days in advance
2. Support old + new contract in parallel
3. Monitor old contract usage
4. Remove old contract after 180 days

### Non-Breaking Changes
**Definition**: Changes consumers can ignore
- Adding optional parameters
- Adding new fields to outputs
- Adding new operations
- Adding new error codes

**Process**:
- Deploy immediately
- Document in changelog
- No consumer updates required

---

## Testing Contracts

### Contract Testing Strategy
- Use contract testing tools (language-agnostic)
- Provider tests verify contract implementation
- Consumer tests verify contract usage
- CI/CD validates contracts haven't broken

### Example Test Scenarios
**CreateUser Operation**:
- ✓ Valid input creates user successfully
- ✓ Duplicate email returns `EmailAlreadyExists`
- ✓ Invalid email returns `InvalidEmail`
- ✓ Missing required field returns `InvalidInput`
- ✓ Rate limit exceeded returns `RateLimitExceeded`
- ✓ Success emits `UserCreated` event

---

## Gate 4 Validation

**Validation Date**: [Date]
**Validated By**: [Person/team]

- [ ] All component contracts defined
- [ ] All operations have inputs/outputs
- [ ] Error scenarios documented
- [ ] Events fully specified
- [ ] External integrations covered
- [ ] No protocol specifics included
- [ ] Ready for Data Modeling (Gate 5)

**Approval**: ☐ Approved | ☐ Needs Revision | ☐ Rejected
**Next Step**: Proceed to Data Modeling (`pre-dev-data-model`)
```

## Common Violations and Fixes

### Violation 1: Protocol-Specific Details
❌ **Wrong**:
```markdown
#### Operation: CreateUser
**Endpoint**: POST /api/v1/users
**Status Codes**:
- 201 Created
- 409 Conflict (email exists)
- 400 Bad Request
```

✅ **Correct**:
```markdown
#### Operation: CreateUser
**Purpose**: Create new user account

**Inputs**: [userId, email, displayName]
**Outputs**: UserCreatedResponse
**Errors**:
- EmailAlreadyExists (email in use)
- InvalidInput (validation failure)
```

### Violation 2: Implementation in Contract
❌ **Wrong**:
```markdown
**Validation**:
```javascript
if (!/^[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$/.test(email)) {
  throw new ValidationError("Invalid email");
}
```
```

✅ **Correct**:
```markdown
**Validation Rules**:
- `email` must match email format per RFC 5322
- Pattern: local@domain.tld
- Max length: 254 characters
```

### Violation 3: Technology-Specific Types
❌ **Wrong**:
```markdown
**Output**:
```json
{
  "userId": "uuid",
  "createdAt": "Date",
  "profile": "Map<String, Any>"
}
```
```

✅ **Correct**:
```markdown
**Outputs**:
| Field | Type | Description |
|-------|------|-------------|
| userId | Identifier | UUID format |
| createdAt | Timestamp | ISO8601 timestamp |
| profile | ProfileObject | User profile data |
```

## Confidence Scoring

Use this to adjust your interaction with the user:

```yaml
Confidence Factors:
  Contract Completeness: [0-30]
    - All operations documented: 30
    - Most operations covered: 20
    - Significant gaps: 10

  Interface Clarity: [0-25]
    - Clear, unambiguous contracts: 25
    - Some interpretation needed: 15
    - Vague or conflicting: 5

  Integration Complexity: [0-25]
    - Simple point-to-point: 25
    - Moderate dependencies: 15
    - Complex orchestration: 5

  Error Handling Coverage: [0-20]
    - All scenarios documented: 20
    - Common cases covered: 12
    - Minimal coverage: 5

Total: [0-100]

Action:
  80+: Generate complete contracts autonomously
  50-79: Present options for user selection
  <50: Ask clarifying questions about integration needs
```

## Output Location

**Always output to**: `docs/pre-development/api-design/api-contracts-[feature-name].md`

## After API Design Approval

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

## Quality Self-Check

Before declaring API Design complete, verify:
- [ ] All TRD integration points have contracts
- [ ] Operations are clearly named and described
- [ ] Inputs are fully specified (type, required, constraints)
- [ ] Outputs are complete (all fields documented)
- [ ] Error scenarios are comprehensive
- [ ] Events have full payload specifications
- [ ] Validation rules are explicit
- [ ] Rate limits are defined
- [ ] Idempotency is documented where relevant
- [ ] Zero protocol specifics (REST/gRPC/etc)
- [ ] Zero implementation code
- [ ] Contracts are testable
- [ ] Backward compatibility strategy exists
- [ ] Gate 4 validation checklist 100% complete

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

Violating this separation means:
- You're locked into a protocol before evaluating alternatives
- Contracts can't be reused across different delivery mechanisms
- You can't objectively compare REST vs. gRPC vs. messaging
- Teams can't work in parallel with clear interface agreements

**Define the contract. Stay abstract. Choose protocol later.**