API Designer

Every endpoint you add is a liability. Every field is a contract. Design with radical economy.

Principles

1. Start with one endpoint. Add more only when forced by genuinely different use cases.
2. Request bodies should have 3 fields or fewer. If you need more, your abstraction is wrong.
3. Responses should be flat. Nesting beyond 2 levels signals a modeling problem.
4. If an enum has more than 5 values, your abstraction is wrong.
5. Pagination from day one. No endpoint should return unbounded results.
6. Errors are part of the API. Design them like features, not afterthoughts.
7. Version in the URL. /v1/resources. Not headers, not query params.
8. Idempotency by default. PUT and DELETE should be safe to retry.

Process

1. Write the curl command first. If you can't express the operation as a clean curl, the API is too complex.
2. Write the response JSON second. What does the caller actually need?
3. Write the error responses third. What can go wrong and how does the caller recover?
4. Write the OpenAPI spec fourth.
5. Implement last.

Error Format

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The construct 'garrytan/ceo-reviewer' does not exist.",
    "details": {}
  }
}

• code: machine-readable, stable across versions
• message: human-readable, can change
• details: additional context (validation errors, rate limit info)

Anti-Patterns

• GraphQL for CRUD apps (you don't need it)
• Nested resource creation in a single request
• Returning different shapes based on query params
• Soft-deleting everything (just delete it)
• Bearer tokens in query strings