[Feature] : API ENDPOINTS PR 4 : Samples Endpoints

[pulk17]

[FEATURE]

In raising this pull request, I confirm the following (please check boxes):

• I have read and understood the contributors guide.
• I have checked that another pull request for this purpose does not exist.
• I have considered, and confirmed that this submission will be valuable to others.
• I accept that this submission may not be used, and the pull request closed at the will of the maintainer.
• I give this submission freely, and claim no ownership to its content.

My familiarity with the project is as follows (check one):

• I have never used the project.
• I have used the project briefly.
• I have used the project extensively, but have not contributed previously.
• I am an active contributor to the project.

---

Samples endpoints (PR 4/6)

Summary

Part 4 of 6 (supersedes #1117). Adds endpoints for media samples, their per-run
results, cross-run history, and the regression-test catalogue. (Baseline
approval is in PR 5, since it operates on result data.)

Stacking: stacked on PR 3 (#1132). Please review #1132 first.

Endpoints (mod_api/routes/samples.py)

• GET /runs/{run_id}/samples — per-run results, one row per regression test,
  with ?status/?name/?tag/?category. Status uses the same expected-output
  comparison as /runs/{id}/summary, so the two can't disagree.
• GET /runs/{run_id}/samples/{regression_test_id} — a single result within a
  run. The path id is the regression_test_id, not Sample.id (a "sample
  within a run" is identified by its regression test); the response carries both.
• GET /samples — catalogue; ?name (LIKE-escaped), ?extension, ?sha256,
  ?tag, ?status=active|inactive. Filtered + paginated at the DB level.
• GET /samples/{sample_id} — sample metadata.
• GET /samples/{sample_id}/history — cross-run history with a
  failure_signature to separate genuine regressions from infra flakes;
  batch-loads to avoid N+1.
• GET /regression-tests — definitions; ?active (defaults true), ?category,
  ?tag, ?sample_id.

Schemas / tests

schemas/samples.py serializes samples/results/history without leaking internal
relationships. tests/base.py gains setup_run_data() and get_token() to cut
duplication across API tests.

Testing

145 tests; history verified against N+1 regressions; tag/offset edge cases
covered. Lint/type clean. (Consolidated caveats are in PR 6.)

Next

PR 5 (#1134): results data and baseline approvals.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud