Skip to content

api-reference.md

Latest commit

 

History

History
236 lines (157 loc) · 3.36 KB

api-reference.md

File metadata and controls

236 lines (157 loc) · 3.36 KB

API Reference

All endpoints require authentication. Use these headers:

# Admin access (create/update/delete)
-H "Authorization: Bearer secret-admin-123"

# User access (read-only)
-H "Authorization: Bearer secret-user-123"

Task Management

List All Tasks

GET /tasks

Returns array of all tasks.

Get One Task

GET /tasks/:id

Returns a specific task by ID.

Create Task

POST /tasks
Content-Type: application/json

{
  "title": "Task name",
  "priority": 5,
  "dependencies": []
}

Returns the created task with generated ID.

Update Task

PUT /tasks/:id
Content-Type: application/json

{
  "title": "New title",
  "priority": 8
}

Returns updated task.

Delete Task

DELETE /tasks/:id

Returns success.

Data Access

Get Queue Structure

GET /tasks/queue

Returns the internal Max-Heap structure (for learning).

Get Highest Priority Task

GET /tasks/peek

Same as /tasks/next, returns top priority task.

Get Next Task

GET /tasks/next

Returns highest priority task without removing it.

Dependency Resolution

Resolve All Tasks

GET /tasks/resolve

Returns execution order for all tasks (topological sort).

Status codes:

  • 200 — Success, execution order found
  • 409 — Conflict, cycle detected (impossible)
  • 422 — Unprocessable, missing dependency

Resolve Single Task

GET /tasks/:id/resolve

Returns execution order for this task and its dependencies.

Streaming Exports

CSV Export

GET /tasks/export.csv

Returns tasks as CSV, suitable for Excel/Google Sheets.

NDJSON Stream

GET /tasks/stream.ndjson

Returns tasks as newline-delimited JSON, one per line.

Processing

Start Report Job

POST /tasks/reports/start?heavyIterations=1000000

Starts CPU-intensive report in worker thread.

Returns:

{ "jobId": "abc-123-def" }

Get Report Status

GET /tasks/reports/:jobId

Returns one of:

{ "status": "processing", "progress": "..." }
{ "status": "complete", "result": 123456 }
{ "status": "error", "error": "..." }

Get Worker Stats

GET /tasks/reports/stats

Returns worker pool statistics.

Monitoring

Memory Usage

GET /tasks/system/memory

Returns heap usage, RSS, and garbage collection info.

WebSocket Hub Stats

GET /tasks/system/ws

Returns number of connected clients and active subscriptions.

Real-Time

WebSocket Connection

WS /ws/tasks

Listen for events:

{ "event": "task.created", "task": { ... } }
{ "event": "task.updated", "task": { ... } }
{ "event": "task.deleted", "taskId": "..." }

Error Responses

All errors follow this format:

{
  "error": "Human-readable message",
  "code": "MACHINE_CODE",
  "httpStatus": 400,
  "requestId": "request-uuid",
  "timestamp": "2024-01-15T10:30:00Z"
}

Common status codes:

  • 200 — Success
  • 201 — Created
  • 400 — Bad request (invalid data)
  • 401 — Unauthorized (missing/invalid token)
  • 403 — Forbidden (insufficient permissions)
  • 404 — Not found
  • 409 — Conflict (cycle detected)
  • 422 — Unprocessable entity (malformed data)
  • 500 — Server error

Testing

See scripts/full-demo.sh for comprehensive examples of every endpoint.