API Operations Use Cases (API)¶
UC-API-001: Get Patient by ABHA ID¶
Purpose: Retrieve full longitudinal record for UI.
| Property | Value |
|---|---|
| Actor | Frontend Application |
| Trigger | User navigates to Patient Overview |
| Priority | P0 |
Main Success Scenario:
1. Frontend requests `GET /api/patients/ABHA-12345`
2. API Gateway validates JWT (Scope: `read:patient`)
3. Query Service checks Redis cache `patient:ABHA-12345`
4. If miss, load `bundle.json` from S3
5. Return JSON response (200 OK)
Acceptance Criteria: 1. [ ] Response time < 200ms (cached) 2. [ ] Returns 404 if patient not found
UC-API-002: Upload Document¶
Purpose: Physician uploads a PDF report.
| Property | Value |
|---|---|
| Actor | Physician |
| Trigger | "Upload Report" button clicked |
| Priority | P1 |
Main Success Scenario:
1. Frontend sends multipart POST to `/api/upload/document`
2. API validates file type (PDF) and size (<10MB)
3. API saves to S3 `raw/` bucket
4. API triggers **UC-PROC-001** (Queue OCR Job)
5. Return 202 Accepted with `jobId`
Acceptance Criteria: 1. [ ] Validates MIME type (no executables) 2. [ ] Enforces per-user rate limits
UC-API-003: Query Job Status¶
Purpose: Poll for completion of async tasks.
| Property | Value |
|---|---|
| Actor | Frontend Application |
| Trigger | Polling interval (2s) |
| Priority | P1 |
Main Success Scenario:
1. Frontend requests `GET /api/jobs/{jobId}`
2. API looks up job in Redis/DB
3. Return status JSON:
`{ "status": "processing", "progress": 45 }`
Acceptance Criteria: 1. [ ] Returns current status and result (if complete) 2. [ ] Handles expired/unknown job IDs
UC-API-004: Generate FHIR Bundle¶
Purpose: Export patient data in standard format using HAPI FHIR.
| Property | Value |
|---|---|
| Actor | External System |
| Trigger | API Request with format=fhir |
| Priority | P1 |
Main Success Scenario:
1. Request `GET /api/patients/{id}?format=fhir`
2. Service loads Canonical Bundle
3. HAPI FHIR Transformer maps fields to FHIR Resources
- Demographics -> Patient
- Labs -> Observation
- Cancer -> Condition
4. Assemble `Bundle` resource using HAPI FHIR IParser
5. Return `application/fhir+json`
Acceptance Criteria: 1. [ ] Validates against FHIR R4 profiles using HAPI Validator 2. [ ] Includes Provenance resources
UC-API-005: Search Patients¶
Purpose: Provide faceted search over the active patient roster.
| Property | Value |
|---|---|
| Actor | Frontend Application |
| Trigger | User types into global search bar |
| Priority | P0 |
Main Success Scenario:
1. Frontend calls `GET /api/patients?query={text}&filters=status:active`
2. API validates query length (>=3 chars) and scopes
3. Search service queries Elasticsearch index `patients`
4. Apply filters (status, tumorSite, treatingPhysician)
5. Return paginated response with highlights
6. Cache search results for 30s keyed by user + query
Acceptance Criteria: 1. [ ] Supports prefix search on name and ABHA ID 2. [ ] Returns <= 50 results per page 3. [ ] Enforces RBAC (users only see assigned cohort)
UC-API-006: Issue Presigned Upload URL¶
Purpose: Allow large uploads directly to object storage without proxying through API servers.
| Property | Value |
|---|---|
| Actor | Frontend Application |
| Trigger | User clicks "Upload" before selecting file |
| Priority | P1 |
Main Success Scenario:
1. Client calls `POST /api/uploads/presign` with payload (patientId, fileType)
2. API validates patient access + fileType whitelist
3. Generate S3 presigned PUT URL (10 min expiry)
4. Return URL + required headers to client
5. Client uploads file directly to S3
6. Client notifies backend via `POST /api/uploads/complete` containing object key
7. Backend enqueues OCR job referencing uploaded object
Acceptance Criteria: 1. [ ] Presigned URLs scoped to specific content-type/size 2. [ ] Upload completion call idempotent 3. [ ] Audit log captures who requested the URL
UC-API-007: Cancel Background Job¶
Purpose: Allow clinicians to stop long-running OCR/ASR jobs before completion.
| Property | Value |
|---|---|
| Actor | Frontend Application |
| Trigger | User clicks "Cancel" on job card |
| Priority | P1 |
Main Success Scenario:
1. Client sends `POST /api/jobs/{jobId}/cancel`
2. API checks ownership + current status (queued|processing)
3. Publish cancel command to worker queue via `job.cancel` topic
4. Worker acknowledges and stops processing (if running)
5. Job status updated to `cancelled` with timestamp + actor
6. Frontend receives updated status via polling or SSE
Alternative Flows:
Alt-1: Job Already Completed
- API returns 409 Conflict - Frontend shows toast "Job already finished"Acceptance Criteria: 1. [ ] Cancellation propagates within 5s for queued jobs 2. [ ] Partial outputs cleaned up from storage 3. [ ] Audit trail records cancellation reason
UC-API-008: Subscribe to Event Stream¶
Purpose: Deliver real-time notifications for job status, alerts, and patient updates without polling.
| Property | Value |
|---|---|
| Actor | Frontend Application |
| Trigger | User opens dashboard |
| Priority | P2 |
Main Success Scenario:
1. Frontend establishes SSE connection `GET /api/events/stream`
2. Gateway authenticates JWT and upgrades to stream
3. Server subscribes user to topics (jobs, alerts, patients)
4. When events occur, server sends JSON payloads with `event:` prefix
5. Client updates UI (job card, alerts tab) in real-time
6. Heartbeat event every 15s keeps connection alive
Acceptance Criteria:
1. [ ] Supports >500 concurrent streams per node
2. [ ] Reconnect logic resumes last event via Last-Event-ID
3. [ ] Downgrades to polling if SSE unsupported