Moai Ref API Patterns

API Patterns Reference

Target Spawn

Backend domain work spawned via Agent(general-purpose) with backend instructions - Applies these patterns directly to API implementation and review.

RESTful API Design Conventions

HTTP Status Code Guide

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "details": [
      {"field": "email", "message": "Must be a valid email address"},
      {"field": "age", "message": "Must be between 0 and 150"}
    ],
    "request_id": "req_abc123"
  }
}

Rules:

• Never expose stack traces or internal details in production
• Always include request_id for traceability
• Use consistent error codes (ENUM, not free text)
• Login failures: "Invalid email or password" (never reveal which)

Pagination Pattern

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

For cursor-based (large datasets):

{
  "data": [...],
  "cursor": {
    "next": "eyJpZCI6MTAwfQ==",
    "has_more": true
  }
}

Input Validation Checklist

Rate Limiting Strategy

Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After (on 429).

API Versioning Strategy

Breaking changes that require version bump:

• Removing or renaming fields
• Changing field types
• Removing endpoints
• Changing authentication methods

Non-breaking changes (no version bump needed):

• Adding new optional fields
• Adding new endpoints
• Adding new query parameters

Common Rationalizations

Hyrum's Law: Every observable API behavior will eventually be depended on by clients. Undocumented response fields, error formats, and timing characteristics become implicit contracts.

Red Flags

• API returns different error formats across endpoints
• Resource names use verbs instead of nouns (e.g., /getUser instead of /users/:id)
• No pagination on list endpoints that can return unbounded results
• Breaking change deployed without API version bump
• GraphQL schema allows unbounded depth or circular queries without limits

Verification

• All endpoints follow consistent naming convention (nouns, plurals, nested resources)
• Error responses use a standard format with machine-readable error code
• List endpoints implement pagination with documented limits
• API versioning strategy present and enforced (URL path, header, or query param)
• Breaking vs non-breaking change classification documented for recent changes
• Input validation returns 400 with specific field-level error details