Skip to content

Finalize native REST v1 API standardization before RC1

Workflow status is tracked in GitHub: https://github.com/emulebb/emulebb/issues/34. This local document is retained as an engineering spec/evidence record.

Summary

Finish the native /api/v1 contract decisions before publishing 0.7.3-rc.1. The current OpenAPI contract and native route seam match exactly, but a few standardization decisions still need to be closed before the public release candidate freezes route and schema shape.

This is release-hardening work for the existing surface. It should not expand REST scope or add unrelated controller features.

Review Evidence

The 2026-05-26 review found:

  • docs/rest/REST-API-OPENAPI.yaml and srchybrid/WebServerJsonSeams.h expose the same 88 native operations.
  • The native seam already enforces strict method, path, body, query, lifecycle, and destructive-confirmation validation.
  • Success envelopes are consistently shaped as { data, meta }; collection routes use data.items, and the intentionally paged lists expose total, offset, and limit.
  • Remaining risks are contract-publication risks: OpenAPI error response visibility, destructive operation route shape, exact error envelope requirements, endpoint selector vocabulary, and naming exceptions.

Scope

  1. Attach native error responses to the OpenAPI operation table. The implementation maps stable error codes to 400, 401, 404, 405, 409, 500, and 503, but the OpenAPI path table currently advertises only 200 success responses.
  2. Replace pre-RC body-required destructive DELETE routes with body-free DELETE resources. Destructive disk deletion uses explicit subresources plus confirm=true, for example /transfers/{hash}/files and /shared-files/{hash}/file.
  3. Make the error envelope contract exact. If error.details is mandatory in runtime responses, require it in OpenAPI and tests.
  4. Decide the stable endpoint selector vocabulary for serverId and endpoint-shaped clientId, especially before IPv6/bracketed endpoint work lands.
  5. Document or normalize the few non-/operations/... action routes: POST /app/shutdown, POST /diagnostics/dumps, and POST /diagnostics/crash-tests.
  6. Keep the route seam, OpenAPI contract, human REST contract, smoke harness, and controller guide in sync in the same implementation slice.

Non-Goals

  • Do not add new REST resource families.
  • Do not broaden qBittorrent or Torznab adapter compatibility.
  • Do not change eD2K/Kad protocol behavior.
  • Do not solve large-list performance here; that remains tracked by FEAT-068.
  • Do not add an external gateway or generated SDK here; broader REST tooling remains tracked by FEAT-014.

Acceptance Criteria

  • [x] OpenAPI documents native error responses and status codes consistently.
  • [x] Runtime error envelope, OpenAPI ErrorEnvelope, and smoke tests agree on required fields.
  • [x] Destructive route shape is explicitly decided and implemented before RC1, with no stale alias routes left unless intentionally documented.
  • [x] Endpoint selector patterns are documented as stable v1 behavior or deferred behind an explicit future compatibility note.
  • [x] Operation-route naming exceptions are either normalized or documented as intentional.
  • [x] Native route seam, OpenAPI route table, REST contract docs, and live smoke registry still report no drift.
  • [x] aMuTorrent, qBit-compatible, and Torznab adapter behavior remains unchanged except for any documented native v1 contract adjustment.

Validation

  • Run the native Web API test slice.
  • Run the REST/OpenAPI Python tests.
  • Run the smallest live REST smoke that proves route-envelope compatibility.
  • For any route-shape change, update aMuTorrent/controller compatibility checks or document why no adapter change is required.

Notes

This item is a blocker for freezing the public native v1 API at 0.7.3-rc.1. It may close by explicitly deciding to preserve the current shape where the review raised compatibility concerns, but those decisions must be written into the OpenAPI contract and human REST contract before RC1.

Closed in GitHub on 2026-05-26 after implementation and validation evidence was posted to https://github.com/emulebb/emulebb/issues/34.

2026-05-26 implementation decision:

  • Native v1 DELETE requests are body-free.
  • DELETE /transfers/{hash} is non-destructive for completed transfer rows; incomplete transfer cancellation with local data removal is DELETE /transfers/{hash}/files?confirm=true.
  • DELETE /shared-files/{hash} unshares/excludes without deleting from disk; disk deletion is DELETE /shared-files/{hash}/file?confirm=true.
  • DELETE /searches?confirm=true replaces the pre-RC delete-all-searches JSON confirmation body.
  • POST /app/shutdown, POST /diagnostics/dumps, and POST /diagnostics/crash-tests remain documented command endpoints for RC1.