REST API Assessment — Study App (formed 14 Apr 2026)

Overview

Compare the HTTP API to common good practice, score it (Table 2), and track prioritized gaps (section 4.3).

Scope and methodology

Scope

This review covers the Study App HTTP API in this repo: runtime behavior, OpenAPI contract, ops endpoints, security defaults, metrics, and CI around the public API. Audience: engineers and stakeholders asking how close we are to common “platform API” ideas for a small / PET-scale service (one app, not a global gateway).

User under /api/v1 is the main example; the same patterns (idempotency, errors) apply elsewhere. Items we only describe as industry practice (e.g. ETag/If-Match) are labeled when not in code today.

Tables match the repo on this assessment date. If behavior changes, update Table 2. The User API has create / read / update / patch by composite key and no list endpoint—pagination is “not applicable yet,” not “missing.”

Method

The review proceeds in four steps:

1. Reference list — Table 1 describes good HTTP/API practices in neutral terms.
2. Map to code — Table 2 scores each practice (1–10) for this repo, with evidence (paths, tools, ADRs).
3. Summarize — overall score and gaps in section 4 (narrative, Table 2 mean, Top‑five gap status).
4. Follow up — page history.

Scores are subjective guesses (PET / integration API lens), not a certification.

What was examined

• Application entrypoint and middleware (app/main.py): request logging, body size limits, authentication, rate limiting, security headers, request context.
• Correlation identifiers (app/core/request_context.py, app/core/logging.py).
• Write idempotency (app/core/idempotency.py, app/repositories/idempotency_repository.py, user routes).
• API contract and documentation pipeline: OpenAPI generation, custom builder, Swagger UI, app/openapi/, baseline and governance scripts.
• Configuration and deployment hints (app/core/config.py, env/, container image).
• Quality gates relevant to the API contract: Makefile targets, .github/workflows/ci.yml, OpenAPI baseline and contract tests.

What this assessment is not

• Not a pentest, compliance audit, or threat model.
• Not proof of production readiness or regulatory fit.
• Not a substitute for load tests, chaos tests, or research with real integrators.

Industry context, PET scope, and standards we do not chase (yet)

Big product orgs often use RFC reviews, launch checklists, security programs, and central API catalogs. We use dated HTML with Table 1 (reference) and Table 2 (scores) per ADR 0024.

Study App is a single-service, PET-scale deploy. Some Table 1 rows matter most at platform scale (distributed rate limits, SSO-only, full portals with billing). “Needs attention” often means not worth it yet or later, not “ignored.” Priorities sit in section 4.3 (Top five gaps).

Table: Reference practices

Legend:

• Category = theme
• Practice = short name
• Reference description = expected behavior (stack-neutral)
• Typical benchmark = who often exemplifies the practice

Table: AS-IS situation

One row per Table 1 practice (rows 1–24). Scores are 1–10 (our guess, not a formal audit). Colours come from docs/assets/docs.css (ADR 0024).

Scoring summary

Narrative overall (Table 2 judgment)

Overall (our guess, integration API): about 6.42 / 10.
To move toward top decile: OpenTelemetry / distributed tracing, shared or edge rate limits, HTTP Deprecation / Sunset headers, stable public spec discovery when the product needs it, optional ETag / If-Match for concurrent edits — see section 4.3 (Top five gaps).

Weighted axis model (explicit arithmetic)

Optional cross-check: sum the numeric scores in Table 2 (rows 1–24), then divide by 24. This is not the same math as the narrative 7/10 above (which weights importance by practice); it answers “what is the unweighted mean of the rubric rows?”

Interpretation: several high scores (OpenAPI pipeline, idempotency, request ids) sit alongside deliberate “not built yet” rows (ETag, conditional GET, distributed limits), which pulls the unweighted mean below the qualitative ~7/10 headline.

Top five gaps — priority and workflow status

Status colours: TODO (not started), IN PROGRESS (owned work in flight), DONE (accepted in main). Update started / closed / PR when you pick up or finish work.

Page history

Page history