Skip to content

docs(architecture): list the verbs the named paths actually serve - #422

Merged
argszero merged 1 commit into
mainfrom
docs/api-roster-verb-lists
Oct 19, 2026
Merged

argszero merged 1 commit into
mainfrom
docs/api-roster-verb-lists

Conversation

@argszero

Copy link
Copy Markdown
Owner

Summary

Three lines in the API roster (docs/architecture.md §6) name a path but list fewer methods than that path serves, so a reader who takes the verb list as complete cannot tell that the operation exists.

line was now
API keys POST/GET/DELETE /api/api-keys POST/GET /api/api-keys + PATCH/DELETE /api/api-keys/:id
Share listings POST/GET/PATCH /api/sharings POST/GET /api/sharings + PATCH /api/sharings/:id
Admin GET /api/admin/users GET /api/admin/users + PATCH /api/admin/users/:id (department only)

What each omission cost a reader:

  • Rename a key. PATCH /api/api-keys/:id is how a key gets renamed (dao::rename_api_key); the roster only showed create / list / revoke. The same line also put DELETE on /api/api-keys when the revoke route is /api/api-keys/:id.
  • Edit a listing. The roster showed PATCH on /api/sharings, while the edit route is /api/sharings/:id — the line named the verb but not where it lives.
  • Assign a user to a department. PATCH /api/admin/users/:id is the only write to a user an admin has (UserPatch carries dept_id and nothing else). Without it the roster makes the admin's user list read as read-only.

The section says it groups by functional face rather than listing every route, and that stays true — this change adds no new face, it completes three that were already named. The sibling departments line immediately below already spells out its :id sub-path with its verbs (GET/POST /api/admin/departments + PATCH/DELETE /api/admin/departments/:id), so the shape used here is the one the table itself already established.

The stated authority for this table is router() in src/routes/mod.rs; every verb above was checked against it, and each handler's own doc comment names the same path (/// PATCH /api/api-keys/:id, /// DELETE /api/api-keys/:id, and sharing::patch / admin::patch_user both taking Path(id)).

Related Issue

None — the repository's issue list is empty; this is a documentation correction found by comparing §6 against router().

Changes

  • Documentation only: docs/architecture.md, 3 lines changed. No code, no config, no data-structure change.
  • No configuration or data-structure change, so no example-file sync is needed.

Tests

  • cargo test — 579 passed, 0 failed.
  • cargo fmt --check — passes.
  • No new unit test: this is prose, and no gate parses docs/architecture.md (src/deploy_gate.rs states it does not cover the file, and no other gate reads this table).

Checklist

  • Branch name follows the convention (docs/).
  • Commit message uses Conventional Commits.
  • Single purpose, minimal change.

The §6 roster names a path but listed fewer methods than that path
serves, so a reader taking the verb list as complete could not rename an
API key, could not see where a sharing is edited, and would not know an
admin can assign a user to a department.

The sibling departments line already spells out its :id sub-path with
its verbs; these three now follow the same shape. Verified against
router() in src/routes/mod.rs.
@argszero
argszero merged commit 942e4f1 into main Oct 19, 2026
2 checks passed
@argszero
argszero deleted the docs/api-roster-verb-lists branch October 19, 2026 17:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant