api-design

name	api-design
description	REST API design patterns for SpecFlux. Use when creating new API endpoints, designing request/response schemas, implementing pagination, or updating OpenAPI specifications. Follows Domain-Driven Design with specs organized by domain.

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