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

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, rate limits/quotas, 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 docs/pre-dev/{feature-name}/api-design.md with these sections:

Per-Operation Structure

Event Contract Structure

Additional Sections

Common Violations

Confidence Scoring

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

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.