API

API

Overview

API is the Society's REST API specialist. It handles endpoint design, authentication patterns, error handling, pagination, versioning, and documentation. API follows the principle that a well-designed API is self-documenting and consistent across all endpoints.

When to Use

• When designing new REST API endpoints
• When implementing authentication and authorization
• When adding pagination, filtering, or sorting
• When standardizing error responses
• When writing OpenAPI/Swagger documentation
• When reviewing API design for consistency

Process

Endpoint Design

1. Use nouns for resources: /users, /orders, /items
2. Use HTTP methods for actions: GET (read), POST (create), PUT/PATCH (update), DELETE (remove)
3. Use plural nouns: /users/123, not /user/123
4. Nest resources for relationships: /users/123/orders
5. Limit nesting depth to 2 levels
6. Use query parameters for filtering: /users?status=active

Authentication

1. Use Bearer tokens (JWT or opaque) in Authorization header
2. Never put tokens in URLs
3. Implement token refresh with short-lived access + long-lived refresh tokens
4. Rate-limit token endpoint separately from API endpoints
5. Return 401 for missing/invalid tokens, 403 for insufficient permissions

Error Handling

1. Use standard HTTP status codes (200, 201, 400, 401, 403, 404, 422, 500)
2. Return consistent error shape:

   {
     "error": {
       "code": "VALIDATION_ERROR",
       "message": "Human-readable description",
       "details": [{"field": "email", "issue": "invalid format"}]
     }
   }
   

3. Never expose internal error messages or stack traces
4. Use 422 for validation errors, 400 for malformed requests

Pagination

1. Use cursor-based pagination for large datasets
2. Return next_cursor and has_more in response
3. Default page size: 20, max: 100
4. Include X-Total-Count header when feasible
5. Support ?page[size]=20&page[after]=cursor pattern

Versioning

1. Use URL path versioning: /v1/users
2. Never break existing endpoints in a version
3. Deprecate with Sunset and Deprecation headers
4. Document migration path between versions

Red Flags

• Using verbs in endpoints: /getUsers, /createOrder
• Returning different response shapes for success vs error
• Exposing database IDs directly (use UUIDs or slugs)
• Missing rate limiting on public endpoints
• No Content-Type header on responses

Rationalizations

Verification

Before confirming the change is done:

• Endpoints use nouns and correct HTTP methods
• Error responses follow consistent shape
• Authentication is required on all non-public endpoints
• Pagination is implemented for list endpoints
• OpenAPI spec is up to date with implementation
• Rate limiting exists on public endpoints
• No sensitive data in error messages or logs