TeamFlow API Contract

1. API Standards

Base path:

/api/v1

Content type:

application/json

Authentication:

Authorization: Bearer <token>

Trace header:

X-Trace-ID

The server must return a trace ID in all responses for debugging and audit purposes.

2. Standard Success Response

Single Resource

{
  "data": {
    "id": "uuid",
    "name": "requirement name"
  },
  "meta": {
    "traceId": "trace-id"
  }
}

Paginated List

{
  "data": [
    { "id": "uuid", "name": "item 1" },
    { "id": "uuid", "name": "item 2" }
  ],
  "meta": {
    "page": 0,
    "size": 20,
    "totalElements": 42,
    "totalPages": 3,
    "traceId": "trace-id"
  }
}

3. Standard Error Response

{
  "code": "REQUIREMENT_VERSION_IMMUTABLE",
  "message": "An approved requirement version cannot be edited.",
  "details": {
    "requirementVersionId": "uuid"
  },
  "traceId": "trace-id"
}

4. Common HTTP Status Codes

• 200 OK — Successful GET, PUT, or PATCH
• 201 Created — Successful POST that creates a resource
• 204 No Content — Successful DELETE
• 400 Bad Request — Validation failure or malformed request
• 401 Unauthorized — Missing or invalid authentication
• 403 Forbidden — Authenticated but not authorized
• 404 Not Found — Resource does not exist
• 409 Conflict — Business conflict or optimistic locking failure
• 422 Unprocessable Entity — Invalid workflow transition
• 429 Too Many Requests — Rate limit exceeded
• 500 Internal Server Error — Unexpected server error

5. Pagination

Query parameters:

GET /api/v1/projects/{projectId}/requirements?page=0&size=20&sort=createdAt,desc

Maximum page size should be configurable (default: 50, max: 100).

6. Filtering

Example:

GET /api/v1/projects/{projectId}/requirements?status=APPROVED&priority=HIGH&createdAfter=2024-01-01

Supported filters vary by resource type and are documented in endpoint specifications.

7. Optimistic Locking

Editable resources include a rowVersion field:

{
  "id": "uuid",
  "name": "requirement name",
  "rowVersion": 3
}

A stale update attempt (using outdated rowVersion) returns:

409 CONFLICT
{
  "code": "STALE_VERSION",
  "message": "This resource was modified by another user. Please refresh and try again."
}

8. Key Endpoints (Sample)

Authentication

• POST /api/v1/auth/login — Authenticate and receive bearer token
• POST /api/v1/auth/logout — Invalidate current token
• POST /api/v1/auth/refresh — Refresh access token

Projects

• GET /api/v1/projects — List accessible projects
• POST /api/v1/projects — Create project
• GET /api/v1/projects/{projectId} — Get project details
• PUT /api/v1/projects/{projectId} — Update project

Requirements

• GET /api/v1/projects/{projectId}/requirements — List project requirements
• POST /api/v1/projects/{projectId}/requirements — Create requirement
• GET /api/v1/requirements/{requirementId} — Get requirement detail
• PUT /api/v1/requirements/{requirementId} — Update draft requirement
• POST /api/v1/requirements/{requirementId}/submit — Submit for review
• POST /api/v1/requirements/{requirementId}/approve — Approve requirement
• GET /api/v1/requirements/{requirementId}/versions — List requirement versions

Change Requests

• POST /api/v1/requirements/{requirementId}/changes — Create change request
• GET /api/v1/changes/{changeId} — Get change request detail
• POST /api/v1/changes/{changeId}/analyze — Perform impact analysis
• POST /api/v1/changes/{changeId}/approve — Approve change request

Tasks

• POST /api/v1/projects/{projectId}/tasks — Create task
• GET /api/v1/tasks/{taskId} — Get task detail
• PUT /api/v1/tasks/{taskId} — Update task status

QA

• POST /api/v1/projects/{projectId}/tests — Create test case
• POST /api/v1/tests/{testId}/execute — Record test execution
• POST /api/v1/tests/{testId}/defects — Create defect from failed test

9. Error Codes (Sample)

• REQUIREMENT_VERSION_IMMUTABLE — Attempted to modify an approved requirement version
• UNAUTHORIZED — User lacks required permission
• INVALID_WORKFLOW_TRANSITION — Status transition not allowed
• REQUIREMENT_NOT_FOUND — Referenced requirement does not exist
• STALE_VERSION — Optimistic locking conflict
• DUPLICATE_CHANGE_REQUEST — Similar change request already open

10. Security Headers

All responses include:

Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'self'

Next: Review the Data Model →