Ringpre Dev Api Design

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 | "[email protected]" |
| 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 | "[email protected]" |
| 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, 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: