API Design Patterns

API Design Patterns

Thinking > Copying. This skill is a modular toolkit. Read only the sections relevant to your current task.

📑 Content Map

✅ Decision Checklist

Before writing code:

• Protocol: REST vs GraphQL? (See SKILL.md (original) or rest.md/graphql.md)
• Versioning: URI (/v1/) or Header? (See versioning.md)
• Security: Public (API Key) or User (JWT)? (See security.md)
• Errors: Is the error envelope standard? (See examples/response-envelope.json)
• Docs: Is the OpenAPI spec started? (See examples/openapi-template.yaml)

❌ Anti-Patterns (The "Don't Do" List)

1. Don't use Verbs in URIs: POST /createUser -> POST /users.
2. Don't return raw Arrays: Always wrap in { data: [...] } to allow future metadata.
3. Don't ignore N+1: Use DataLoader (GraphQL) or include (ORM) to prevent DB floods.
4. Don't break clients: Never rename fields without a version bump.
5. Don't leak internals: 500 Server Error with a stack trace is a security risk.

🛠️ Tools

• Linter: Run python scripts/api_linter.py <path_to_openapi.yaml> (TODO) to check your spec.
• Validation: Use examples/zod-validation.ts as a baseline.