Skip to content

Correct three stale API documentation claims #235

Description

@HMarzban

Problem

Two published statements contradict the code.

1. The auth page overstates the service-role key. docs/api/authentication.md §Keep the service-role key on a server says the key "passes every document, public and private". §What each credential can call repeats it for export and import. But §Private documents are owner-only says the slug read ignores the key. A reader who trusts the first line expects the key to open a private document by slug.

2. API.md names the wrong media path. §Error envelope lists "media-upload guards" among the ad-hoc { "error": "..." } shapes. The upload route returns the house envelope (src/api/routers/hypermultimedia.router.ts). The ad-hoc shape comes from media file reads (src/lib/storage/storage.local.ts, storage.s3.ts).

What to do

Documentation only.

  1. Qualify each "passes every document" sentence: on the routes it can call, with the slug read as the one exception. Link to §Private documents are owner-only.
  2. In API.md, replace "media-upload guards" with "media file reads".

Acceptance

  • docs/api/authentication.md never says the key opens every document without naming the slug-read exception.
  • API.md §Error envelope lists media file reads, not media-upload guards.

Notes

The rate-limit item is done: API.md §Rate limiting states the production value, 500.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions