REST API #2e: Standardization cleanup (retrofit FFmpegProfileController, OpenAPI/CORS/docs) #38

Closed
opened 2026-06-27 13:46:23 +02:00 by timothy · 3 comments
Owner

Part of #2 (REST API tracker). Design: docs/rest-api.md. Runs last — folds in cleanup gathered during #2a–#2d.

Slice #2e — Standardization cleanup.

  • Retrofit the existing non-idiomatic FFmpegProfileController (/api/ffmpeg/profiles/new, /update, /delete/{id}) to the idiomatic shape, gated by characterization tests (test-before/after).
  • OpenAPI / Scalar /docs polish: accurate summaries + [ProducesResponseType] across the new endpoints.
  • CORS review for mutation routes (currently AllowAll) now that write endpoints exist.
  • Sweep for any other non-idiomatic /api endpoints; fold in backlog items gathered during #2a–#2d.

Per the working policy: opportunistic fixes found en route are backlogged unless limited-scope + useful-now, or deferral would force rework.

Part of #2 (REST API tracker). Design: `docs/rest-api.md`. Runs last — folds in cleanup gathered during #2a–#2d. **Slice #2e — Standardization cleanup.** - Retrofit the existing non-idiomatic `FFmpegProfileController` (`/api/ffmpeg/profiles/new`, `/update`, `/delete/{id}`) to the idiomatic shape, gated by **characterization tests** (test-before/after). - OpenAPI / Scalar `/docs` polish: accurate summaries + `[ProducesResponseType]` across the new endpoints. - **CORS review for mutation routes** (currently `AllowAll`) now that write endpoints exist. - Sweep for any other non-idiomatic `/api` endpoints; fold in backlog items gathered during #2a–#2d. Per the working policy: opportunistic fixes found en route are backlogged unless limited-scope + useful-now, or deferral would force rework.
Author
Owner

Starting #38 on branch issue38-rest-api-standardization from current origin/main (30ecd9a8).

Approach:

  • First retrofit FFmpegProfileController using TDD/characterization tests: idiomatic routes, API-key write filter, ApiResults ProblemDetails mapping, accurate OpenAPI metadata.
  • Convert FFmpeg profile not-found handler paths that are addressed-resource or referenced-resource misses to NotFoundError so runtime 404/422 matches the REST #2 contract instead of returning plain strings or generic validation bodies.
  • Sweep existing /api routes after the FFmpeg work. Older operational endpoints such as library scan and maintenance may be documented/deferred if they are outside REST #2 CRUD standardization.
  • No EF model changes expected, so no migrations planned.

Verification planned: targeted red/green tests first, LSP diagnostics on changed C# files, scripts/update-openapi.sh, dotnet build ErsatzTV.sln, and TZ=UTC dotnet test ErsatzTV.sln -v normal before PR.

Starting #38 on branch `issue38-rest-api-standardization` from current `origin/main` (`30ecd9a8`). Approach: - First retrofit `FFmpegProfileController` using TDD/characterization tests: idiomatic routes, API-key write filter, `ApiResults` ProblemDetails mapping, accurate OpenAPI metadata. - Convert FFmpeg profile not-found handler paths that are addressed-resource or referenced-resource misses to `NotFoundError` so runtime 404/422 matches the REST #2 contract instead of returning plain strings or generic validation bodies. - Sweep existing `/api` routes after the FFmpeg work. Older operational endpoints such as library scan and maintenance may be documented/deferred if they are outside REST #2 CRUD standardization. - No EF model changes expected, so no migrations planned. Verification planned: targeted red/green tests first, LSP diagnostics on changed C# files, `scripts/update-openapi.sh`, `dotnet build ErsatzTV.sln`, and `TZ=UTC dotnet test ErsatzTV.sln -v normal` before PR.
Author
Owner

Progress

What was done: Opened PR #52 (issue38-rest-api-standardization) for REST API #2e cleanup. The PR retrofits FFmpegProfileController to idiomatic REST routes under /api/ffmpeg/profiles[/{id}], adds stable request DTOs, returns ProblemDetails for FFmpeg profile 404/422/401 paths, regenerates OpenAPI, and updates docs/rest-api.md with the CORS/sweep results. It also applies the optional API-key write filter to legacy mutating library and maintenance API endpoints after adversarial review identified that gap.

Root cause: n/a; this is standardization/cleanup work, not an incident fix. For the review finding, the cause was that the original API-key convention had been applied to REST #2 CRUD controllers but not older mutating /api operational controllers.

Files changed: FFmpeg profile controller/handlers/request DTOs; API-key filter; library/maintenance controllers; controller/filter/handler/OpenAPI tests; generated ErsatzTV/wwwroot/openapi/v1.json; docs/rest-api.md.

Verification: LSP diagnostics on changed C# files reported no diagnostics. scripts/update-openapi.sh succeeded. dotnet build ErsatzTV.sln succeeded with 0 warnings/errors. TZ=UTC dotnet test ErsatzTV.sln -v normal succeeded with 263 passed, 0 failed. Adversarial review was run before PR creation and both findings were fixed before push.

Deferred: CORS remains the existing global AllowAll; tightening it is an operational exposure policy decision if write APIs are exposed beyond LAN. Legacy operational route names such as maintenance/library scan endpoints are still action-style but now covered by API-key write protection; route reshaping is deferred to a separate operational API cleanup if needed.

Follow-up issues: none created.

Docs updated: docs/rest-api.md.

Current status: PR #52 is open and mergeable, but CI is still pending (Build & test (.NET) and EF migration integrity both report Waiting to run; image job is blocked by required conditions). Leaving #38 open until CI is green, PR is merged, and the issue can be closed according to the standing rule.

## Progress **What was done**: Opened PR #52 (`issue38-rest-api-standardization`) for REST API #2e cleanup. The PR retrofits `FFmpegProfileController` to idiomatic REST routes under `/api/ffmpeg/profiles[/{id}]`, adds stable request DTOs, returns `ProblemDetails` for FFmpeg profile 404/422/401 paths, regenerates OpenAPI, and updates `docs/rest-api.md` with the CORS/sweep results. It also applies the optional API-key write filter to legacy mutating library and maintenance API endpoints after adversarial review identified that gap. **Root cause**: n/a; this is standardization/cleanup work, not an incident fix. For the review finding, the cause was that the original API-key convention had been applied to REST #2 CRUD controllers but not older mutating `/api` operational controllers. **Files changed**: FFmpeg profile controller/handlers/request DTOs; API-key filter; library/maintenance controllers; controller/filter/handler/OpenAPI tests; generated `ErsatzTV/wwwroot/openapi/v1.json`; `docs/rest-api.md`. **Verification**: LSP diagnostics on changed C# files reported no diagnostics. `scripts/update-openapi.sh` succeeded. `dotnet build ErsatzTV.sln` succeeded with 0 warnings/errors. `TZ=UTC dotnet test ErsatzTV.sln -v normal` succeeded with 263 passed, 0 failed. Adversarial review was run before PR creation and both findings were fixed before push. **Deferred**: CORS remains the existing global `AllowAll`; tightening it is an operational exposure policy decision if write APIs are exposed beyond LAN. Legacy operational route names such as maintenance/library scan endpoints are still action-style but now covered by API-key write protection; route reshaping is deferred to a separate operational API cleanup if needed. **Follow-up issues**: none created. **Docs updated**: `docs/rest-api.md`. **Current status**: PR #52 is open and mergeable, but CI is still pending (`Build & test (.NET)` and `EF migration integrity` both report `Waiting to run`; image job is blocked by required conditions). Leaving #38 open until CI is green, PR is merged, and the issue can be closed according to the standing rule.
Author
Owner

Done

What was done: Completed REST API #2e standardization cleanup via PR #52. FFmpegProfileController now uses idiomatic REST routes under /api/ffmpeg/profiles[/{id}], request DTOs, ApiResults/ProblemDetails 404/422/401 response bodies, and API-key write protection. OpenAPI was regenerated and documents the new routes/error responses. Legacy mutating /api/libraries/* and /api/maintenance/* endpoints are now covered by ApiKeyAuthorizationFilter as part of the write-auth sweep.

Root cause: n/a for the planned cleanup. Review finding root cause: the API-key write convention had been applied to REST #2 CRUD controllers but older mutating operational /api controllers were not included in that sweep.

Files changed: FFmpeg profile controller/handlers/request DTOs; API-key filter; library/maintenance controllers; controller/filter/handler/OpenAPI tests; generated ErsatzTV/wwwroot/openapi/v1.json; docs/rest-api.md.

Verification: Local LSP diagnostics on changed C# files reported no diagnostics. scripts/update-openapi.sh passed. dotnet build ErsatzTV.sln passed with 0 warnings/errors. TZ=UTC dotnet test ErsatzTV.sln -v normal passed with 263 tests. PR #52 CI passed: Build & test (.NET) successful in 5m12s; EF migration integrity (SQLite + MySql) successful in 6m13s. Pull-request image job was skipped as expected.

Deferred: CORS remains the existing global AllowAll; tightening remains an operational exposure policy decision if write APIs are exposed beyond LAN. Legacy operational route reshaping for library/maintenance actions is deferred to a future operational API cleanup if needed; they are now write-auth protected.

Follow-up issues: none created.

Docs updated: docs/rest-api.md.

Reviewer-facing summary: Adversarial review findings were addressed before merge: legacy mutating API endpoints now use the API-key filter, and 401 responses now return/document ProblemDetails. No disagreements or open reviewer questions.

Merged PR #52 as 4aec234e and deleted branch issue38-rest-api-standardization.

## Done **What was done**: Completed REST API #2e standardization cleanup via PR #52. `FFmpegProfileController` now uses idiomatic REST routes under `/api/ffmpeg/profiles[/{id}]`, request DTOs, `ApiResults`/`ProblemDetails` 404/422/401 response bodies, and API-key write protection. OpenAPI was regenerated and documents the new routes/error responses. Legacy mutating `/api/libraries/*` and `/api/maintenance/*` endpoints are now covered by `ApiKeyAuthorizationFilter` as part of the write-auth sweep. **Root cause**: n/a for the planned cleanup. Review finding root cause: the API-key write convention had been applied to REST #2 CRUD controllers but older mutating operational `/api` controllers were not included in that sweep. **Files changed**: FFmpeg profile controller/handlers/request DTOs; API-key filter; library/maintenance controllers; controller/filter/handler/OpenAPI tests; generated `ErsatzTV/wwwroot/openapi/v1.json`; `docs/rest-api.md`. **Verification**: Local LSP diagnostics on changed C# files reported no diagnostics. `scripts/update-openapi.sh` passed. `dotnet build ErsatzTV.sln` passed with 0 warnings/errors. `TZ=UTC dotnet test ErsatzTV.sln -v normal` passed with 263 tests. PR #52 CI passed: `Build & test (.NET)` successful in 5m12s; `EF migration integrity (SQLite + MySql)` successful in 6m13s. Pull-request image job was skipped as expected. **Deferred**: CORS remains the existing global `AllowAll`; tightening remains an operational exposure policy decision if write APIs are exposed beyond LAN. Legacy operational route reshaping for library/maintenance actions is deferred to a future operational API cleanup if needed; they are now write-auth protected. **Follow-up issues**: none created. **Docs updated**: `docs/rest-api.md`. **Reviewer-facing summary**: Adversarial review findings were addressed before merge: legacy mutating API endpoints now use the API-key filter, and 401 responses now return/document `ProblemDetails`. No disagreements or open reviewer questions. Merged PR #52 as `4aec234e` and deleted branch `issue38-rest-api-standardization`.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#38