api-patterns

name	api-patterns
description	API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
allowed-tools	Read, Write, Edit, Glob, Grep

API Patterns

Think before designing.

Decision Checklist

• Style: REST (Public) vs GraphQL (Complex) vs tRPC (TS Monorepo).
• Versioning: URL (/v1) vs Header.
• Auth: JWT, OAuth, Keys.
• Protection: Rate Limiting, CORS.
• Docs: OpenAPI/Swagger.

---

🧠 Aletheia Reasoning Protocol (API Design)

Protocols are forever. Design with evolution in mind.

1. Generator (Interface Styles)

• Style Options: "Is this a resource graph (GraphQL), a simple resource (REST), or an action (RPC)?".
• Consumer Mapping: "Mobile needs small payloads. Desktop needs high throughput.".
• Version Strategy: "Header versioning vs URL versioning?".

2. Verifier (The Contract Test)

• Chatty Check: "Does the client need 5 calls to show one screen?".
• Breaking Change: "If I rename this field, who breaks?".
• Error Leaks: "Does the 500 status return a stack trace?".

3. Reviser (Simplification)

• Flatten: Reduce nested JSON depth.
• Standardize: Ensure all dates are ISO 8601 UTC.

---

🛡️ Security & Safety Protocol (API)

1. Auth is P0: Never design an "open" API unless clearly public data. Plan AuthN/AuthZ first.
2. Rate Limiting: Every API MUST have rate limiting (Token Bucket/Leaky Bucket) to prevent abuse.
3. Input Validation: Validate ALL inputs. Reject unknown fields (Allowlist over Blocklist).
4. No Enumeration: Use UUIDs or non-sequential IDs to prevent resource scraping.