42 lines
2.0 KiB
Markdown
42 lines
2.0 KiB
Markdown
# QuestionsApi
|
|
|
|
STEP-style question bank service for study games and clients.
|
|
|
|
## Endpoints
|
|
|
|
- `GET /healthz` Health check.
|
|
- `GET /api/questions/systems` List available systems.
|
|
- `POST /api/questions/search` Search or build a block of questions.
|
|
- `GET /api/questions/{id}` Get one question.
|
|
- `POST /api/questions` Create question (SUPER only).
|
|
- `POST /api/questions/bulk` Upsert questions by `externalId` (SUPER only).
|
|
- `PUT /api/questions/{id}` Update question (SUPER only).
|
|
- `DELETE /api/questions/{id}` Delete question (SUPER only).
|
|
- `POST /api/question-reports` Submit a categorized question report (USER or SUPER).
|
|
- `GET /api/question-reports` List and filter reports, newest first (SUPER only).
|
|
- `GET /api/question-reports/{id}` Get a report and its question snapshot (SUPER only).
|
|
- `PATCH /api/question-reports/{id}/status` Resolve or dismiss an open report (SUPER only).
|
|
|
|
Player reads require `USER` or `SUPER` JWT auth. Authoring endpoints require `SUPER`.
|
|
|
|
## Answer tracking
|
|
|
|
The `QuestionAttempts` collection is the immutable source of truth and enforces
|
|
one first attempt per question and user with a unique compound index. Choice
|
|
percentages are served from 32-way materialized counter buckets and cached for
|
|
up to five minutes. A background service backfills counters on the first deploy
|
|
and reconciles recently active questions every five minutes.
|
|
|
|
- `GET /readyz` verifies MongoDB connectivity for readiness checks.
|
|
- `GET /metrics` exposes Prometheus-format service and reconciliation metrics.
|
|
|
|
The manifests in `k8s/` configure 2-10 API replicas. The cluster must have
|
|
Kubernetes Metrics Server installed before applying them with
|
|
`kubectl apply -k k8s/`.
|
|
|
|
Questions submitted through authoring endpoints must have authoritative direct
|
|
reference links recorded as described in the repository's **Question
|
|
Verification References** policy. The references must verify the keyed answer
|
|
and the material claims in the explanation; search-result links are not
|
|
acceptable.
|