API Design Patterns for SpecFlux

RESTful Conventions

Follow these patterns consistently:

Resource Naming

• •Use plural nouns: /tasks, /epics, /projects
• •Nested resources: /projects/:id/tasks
• •Actions as POST to sub-resources: /tasks/:id/start

HTTP Methods

• •GET - Read (list or single)
• •POST - Create or action
• •PUT - Full update
• •PATCH - Partial update
• •DELETE - Remove

Response Codes

• •200 - Success (GET, PUT, PATCH)
• •201 - Created (POST)
• •204 - No Content (DELETE)
• •400 - Bad Request (validation error)
• •404 - Not Found
• •500 - Server Error

Pagination

All list endpoints support pagination:

GET /projects/1/tasks?page=1&limit=20&status=in-progress

Response:
{
  "success": true,
  "data": {
    "tasks": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "pages": 3
    }
  }
}

Filtering & Sorting

GET /tasks?epic_id=5&repo=backend&status=ready&sort=-created_at

// Sort: prefix with '-' for descending

OpenAPI First (Domain-Driven)

API specs are organized by domain in orchestrator/openapi/:

openapi/
├── index.yaml           # Main entry point, references domain specs
├── projects.yaml        # Project domain endpoints
├── epics.yaml           # Epic domain endpoints
├── tasks.yaml           # Task domain endpoints
├── repositories.yaml    # Repository domain endpoints
├── notifications.yaml   # Notification domain endpoints
└── components/          # Shared schemas and responses

Workflow

1. •Update the relevant domain spec (e.g., tasks.yaml)
2. •Add request/response schemas to components/
3. •Generate TypeScript client: npm run generate:client
4. •Implement backend handler
5. •Use generated types in frontend