api-design

API Design

Design APIs that are predictable, versionable, and self-documenting.

Procedure

REST Conventions

• Resources are nouns, plural: /users, /cases, /reflections
• Actions are sub-resources: /users/{id}/sessions
• Verbs only when nothing else fits: /users/{id}/verify-email

HTTP Methods

Status Codes

Error Contract

Every error uses the same shape:

{
  "error": {
    "code": "user_not_found",
    "message": "No user with id 'abc123'",
    "param": "user_id",
    "doc_url": "https://api.example.com/docs/errors#user_not_found"
  }
}

• code: stable, snake_case, machine-readable
• message: human-readable, may include the failing value
• param: which field caused the issue
• doc_url: always present for documented codes

Anti-patterns

• An action encoded as a GET with side effects.
• A new error shape for one endpoint.
• A breaking response change without a version.
• Pagination or idempotency left implicit.

References

• details

Verification Checklist

• [ ] Methods match side effects and idempotency.
• [ ] Status codes follow the table.
• [ ] Errors use the shared object shape.
• [ ] Collection endpoints state pagination.
• [ ] Breaking changes have a version path.