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

• Update the relevant domain spec (e.g., tasks.yaml )

• Add request/response schemas to components/

• Generate TypeScript client: npm run generate:client

• Implement backend handler

• Use generated types in frontend