ColaFlow/docs/api/API-Endpoints-Summary.md

ColaFlow API Endpoints Summary

Base URL: http://localhost:5167

API Documentation: http://localhost:5167/scalar/v1 (Scalar UI)

Last Updated: 2025-11-05 (Day 16)

---

ProjectManagement API Endpoints

Projects (5 endpoints)

Method	Endpoint	Description	Auth	Response
GET	/api/v1/Projects	List all projects for current tenant	Required	200 OK
GET	/api/v1/Projects/{id}	Get project by ID	Required	200 OK
POST	/api/v1/Projects	Create new project	Required	201 Created
PUT	/api/v1/Projects/{id}	Update project	Required	200 OK
DELETE	/api/v1/Projects/{id}	Delete project	Required	204 No Content

Epics (6 endpoints)

Method	Endpoint	Description	Auth	Response
GET	/api/v1/projects/{projectId}/epics	List epics for a project	Required	200 OK
GET	/api/v1/epics/{id}	Get epic by ID	Required	200 OK
POST	/api/v1/projects/{projectId}/epics	Create epic (nested)	Required	201 Created
POST	/api/v1/epics	Create epic (independent)	Required	201 Created
PUT	/api/v1/epics/{id}	Update epic	Required	200 OK

Stories (9 endpoints)

Method	Endpoint	Description	Auth	Response
GET	/api/v1/stories/{id}	Get story by ID	Required	200 OK
GET	/api/v1/epics/{epicId}/stories	List stories for an epic	Required	200 OK
GET	/api/v1/projects/{projectId}/stories	List stories for a project	Required	200 OK
POST	/api/v1/epics/{epicId}/stories	Create story (nested)	Required	201 Created
POST	/api/v1/stories	Create story (independent)	Required	201 Created
PUT	/api/v1/stories/{id}	Update story	Required	200 OK
PUT	/api/v1/stories/{id}/assign	Assign story	Required	200 OK
DELETE	/api/v1/stories/{id}	Delete story	Required	204 No Content

Tasks (11 endpoints)

Method	Endpoint	Description	Auth	Response
GET	/api/v1/tasks/{id}	Get task by ID	Required	200 OK
GET	/api/v1/stories/{storyId}/tasks	List tasks for a story	Required	200 OK
GET	/api/v1/projects/{projectId}/tasks	List tasks for a project (with filters)	Required	200 OK
POST	/api/v1/stories/{storyId}/tasks	Create task (nested)	Required	201 Created
POST	/api/v1/tasks	Create task (independent)	Required	201 Created
PUT	/api/v1/tasks/{id}	Update task	Required	200 OK
PUT	/api/v1/tasks/{id}/status	Update task status	Required	200 OK
PUT	/api/v1/tasks/{id}/assign	Assign task	Required	200 OK
DELETE	/api/v1/tasks/{id}	Delete task	Required	204 No Content

Total ProjectManagement Endpoints: 31

---

Authentication API Endpoints

Auth (9 endpoints)

Method	Endpoint	Description	Auth	Response
POST	/api/Auth/login	User login	No	200 OK
GET	/api/Auth/me	Get current user	Required	200 OK
POST	/api/Auth/refresh	Refresh access token	No	200 OK
POST	/api/Auth/logout	Logout current session	Required	200 OK
POST	/api/Auth/logout-all	Logout all sessions	Required	200 OK
POST	/api/Auth/verify-email	Verify email address	No	200 OK
POST	/api/Auth/resend-verification	Resend verification email	No	200 OK
POST	/api/Auth/forgot-password	Request password reset	No	200 OK
POST	/api/Auth/reset-password	Reset password	No	200 OK
POST	/api/Auth/invitations/accept	Accept tenant invitation	No	200 OK

---

Identity & Tenant Management API Endpoints

Tenants (3 endpoints)

Method	Endpoint	Description	Auth	Response
POST	/api/Tenants/register	Register new tenant	No	200 OK
GET	/api/Tenants/{slug}	Get tenant by slug	No	200 OK
GET	/api/Tenants/check-slug/{slug}	Check if slug is available	No	200 OK

Tenant Invitations (3 endpoints)

Method	Endpoint	Description	Auth	Response
POST	/api/tenants/{tenantId}/invitations	Invite user to tenant	Required	200 OK
GET	/api/tenants/{tenantId}/invitations	List tenant invitations	Required	200 OK
DELETE	/api/tenants/{tenantId}/invitations/{invitationId}	Revoke invitation	Required	200 OK

Tenant Users (5 endpoints)

Method	Endpoint	Description	Auth	Response
GET	/api/tenants/{tenantId}/users	List tenant users (with pagination)	Required	200 OK
POST	/api/tenants/{tenantId}/users/{userId}/role	Assign role to user	Required	200 OK
PUT	/api/tenants/{tenantId}/users/{userId}/role	Update user role	Required	200 OK
DELETE	/api/tenants/{tenantId}/users/{userId}	Remove user from tenant	Required	200 OK
GET	/api/tenants/{tenantId}/users/../roles	List available roles	Required	200 OK

Total Identity Endpoints: 20

---

SignalR Hub Endpoints (Real-time)

Hubs (2 WebSocket connections)

Endpoint	Description	Auth
/hubs/project	Project updates (real-time)	Required
/hubs/notification	User notifications (real-time)	Required

SignalR Test Endpoints (5 endpoints)

Method	Endpoint	Description	Auth	Response
POST	/api/SignalRTest/test-user-notification	Test user notification	Required	200 OK
POST	/api/SignalRTest/test-tenant-notification	Test tenant notification	Required	200 OK
POST	/api/SignalRTest/test-project-update	Test project update	Required	200 OK
POST	/api/SignalRTest/test-issue-status-change	Test issue status change	Required	200 OK
GET	/api/SignalRTest/connection-info	Get connection info	Required	200 OK

Total Real-time Endpoints: 7

---

Grand Total

Category	Endpoint Count
ProjectManagement	31
Authentication	10
Identity & Tenants	20
Real-time (SignalR)	7
TOTAL	68 endpoints

---

Key API Groups for Frontend

Essential for Day 18 Frontend Development:

1. Authentication (Priority: CRITICAL)

   • POST /api/Auth/login
   • GET /api/Auth/me
   • POST /api/Auth/refresh
   • POST /api/Auth/logout

2. Projects (Priority: HIGH)

   • GET /api/v1/Projects
   • GET /api/v1/Projects/{id}
   • POST /api/v1/Projects
   • PUT /api/v1/Projects/{id}
   • DELETE /api/v1/Projects/{id}

3. Epics (Priority: HIGH)

   • GET /api/v1/projects/{projectId}/epics
   • POST /api/v1/projects/{projectId}/epics
   • PUT /api/v1/epics/{id}

4. Stories (Priority: HIGH)

   • GET /api/v1/epics/{epicId}/stories
   • POST /api/v1/epics/{epicId}/stories
   • PUT /api/v1/stories/{id}
   • PUT /api/v1/stories/{id}/assign

5. Tasks (Priority: HIGH)

   • GET /api/v1/stories/{storyId}/tasks
   • GET /api/v1/projects/{projectId}/tasks (with filters)
   • POST /api/v1/stories/{storyId}/tasks
   • PUT /api/v1/tasks/{id}/status
   • PUT /api/v1/tasks/{id}/assign

6. Tenants (Priority: MEDIUM)

   • POST /api/Tenants/register
   • GET /api/tenants/{tenantId}/users

7. Real-time (Priority: MEDIUM - Phase 2)

   • /hubs/project (WebSocket)
   • /hubs/notification (WebSocket)

---

Authentication Flow

1. POST /api/Tenants/register           → Register tenant + admin user
2. POST /api/Auth/login                 → Get JWT access token + refresh token
3. Use "Authorization: Bearer <token>"  → For all subsequent API calls
4. POST /api/Auth/refresh               → Refresh expired access token
5. POST /api/Auth/logout                → Logout and invalidate refresh token

---

Typical Frontend Workflow

Creating a Project with Epics and Stories:

1. GET /api/v1/Projects                     → List existing projects
2. POST /api/v1/Projects                    → Create new project
3. POST /api/v1/projects/{id}/epics         → Create epic under project
4. POST /api/v1/epics/{epicId}/stories      → Create story under epic
5. POST /api/v1/stories/{storyId}/tasks     → Create task under story
6. PUT /api/v1/tasks/{id}/assign            → Assign task to user
7. PUT /api/v1/tasks/{id}/status            → Update task status (Kanban board)

---

API Design Patterns

1. Nested Resources (RESTful)

• Nested: POST /api/v1/projects/{projectId}/epics
• Independent: POST /api/v1/epics

Both patterns are supported for flexibility.

2. Action-based Endpoints

• PUT /api/v1/tasks/{id}/assign
• PUT /api/v1/tasks/{id}/status

Specific actions use dedicated endpoints for clarity.

3. Query Parameters for Filtering

• GET /api/v1/projects/{projectId}/tasks?status=InProgress&assigneeId={userId}

---

Multi-Tenant Security Notes

All ProjectManagement endpoints enforce tenant isolation:

• The tenantId is extracted from JWT token
• DO NOT send tenantId in request bodies
• 404 responses prevent information leakage
• Cross-tenant access is impossible

Verified by 7 integration tests.

---

Response Format

Success Response (Example: GET Project)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "ColaFlow Development",
  "key": "COLA",
  "description": "Main development project",
  "status": "Active",
  "ownerId": "user-guid",
  "createdAt": "2025-11-01T10:00:00Z",
  "updatedAt": "2025-11-05T15:30:00Z",
  "epics": []
}

Error Response (RFC 7807)

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "status": 404,
  "detail": "Project with ID 'xxx' not found",
  "instance": "/api/v1/Projects/xxx"
}

---

Frontend Development Checklist

• Set up API client with JWT authentication
• Generate TypeScript types from OpenAPI spec
• Implement authentication flow (login, refresh, logout)
• Create React Query hooks for Projects API
• Create React Query hooks for Epics API
• Create React Query hooks for Stories API
• Create React Query hooks for Tasks API
• Implement error handling for ProblemDetails responses
• Set up WebSocket connection for SignalR (Phase 2)
• Add loading states and error boundaries

---

Quick Links

• Scalar UI: http://localhost:5167/scalar/v1
• OpenAPI JSON: http://localhost:5167/openapi/v1.json
• API Reference: ProjectManagement-API-Reference.md
• Backend Tests: 7/7 Integration Tests Passing

---

Status: Production Ready (95%)

Generated: 2025-11-05 (Day 16)

Backend Team: Ready to support frontend integration