REST Conventions

These guidelines establish consistent API patterns across the platform. All new endpoints must follow these conventions.

Resource Naming Conventions

Use plural nouns for resource collections. Avoid verbs in URLs — let HTTP methods express the action. Nest resources only one level deep to avoid brittle coupling.

# Good
GET    /api/v1/users
GET    /api/v1/users/{id}
GET    /api/v1/users/{id}/projects
POST   /api/v1/projects

# Avoid
GET    /api/v1/getUsers
GET    /api/v1/users/{id}/projects/{pid}/tasks/{tid}/comments

Error Response Format

All errors follow a consistent envelope. The code field is a machine-readable string, while message is human-readable. Always include a request_id for debugging.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "User with ID 42 was not found",
    "request_id": "req_abc123",
    "details": []
  }
}

Pagination

Use cursor-based pagination for collections. Return a next_cursor field when more results are available. Clients pass the cursor via the after query parameter.

Query Parameters

• limit — Number of items per page (default: 20, max: 100)
• after — Cursor for next page
• sort — Sort field (e.g., created_at)
• order — Sort direction (asc or desc)

Rate Limiting

Include rate limit headers on every response. When limits are exceeded, return 429 Too Many Requests with a Retry-After header.

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1709942400