`c1b73b6`

docs/api: document JSON error envelope, X-OAuth-Scopes, rate limits, meta

Authored by mfwolffe <wolffemf@dukes.jmu.edu> yesterday

SHA: c1b73b679648f695821bdfa9689c38a61854211b
Parents: 7f5534e
Tree: 8a39993

1 changed file

Status	File	+	-
M	`docs/public/api/overview.md`	54	9

docs/public/api/overview.mdmodified

  `Authorization: token shp_…` is also accepted as a synonym.
  A request with no `Authorization` header — or with an invalid /
--expired / revoked PAT — returns `401 Unauthorized` with:
++expired / revoked PAT — returns `401 Unauthorized` with the
++canonical JSON error envelope. The response also carries a
++`WWW-Authenticate: Bearer realm="shithub", error="invalid_token"`
++challenge so HTTP-aware clients can reauthenticate cleanly.
  ```json
--{"error": "unauthenticated"}
++{"error": "invalid token"}
  ```
  A request whose PAT lacks the scope a route requires returns
--`403 Forbidden` with:
++`403 Forbidden` with the required scope surfaced in the
++`X-Accepted-OAuth-Scopes` response header. The token's actual
++scopes are echoed on every PAT-authenticated response (including
++errors) via `X-OAuth-Scopes`, so clients can build precise
++"missing scope X, present scopes Y, Z" error messages without
++parsing the body:
--```json
++```
--{"error": "insufficient scope"}
++HTTP/1.1 403 Forbidden
++X-OAuth-Scopes: user:read
++X-Accepted-OAuth-Scopes: repo:write
++Content-Type: application/json; charset=utf-8
++
++{"error":"token lacks required scope: repo:write"}
  ```
  ## Scopes
    conventional HTTP status.
  - **Cache-Control:** every API response sets `no-store`.
  - **Pagination:** list endpoints accept `?per_page=` (default 30,
--  max 100) and return a `Link:` header with `next`, `prev`,
++  max 100) and return an RFC 8288 `Link:` header with `next`,
--  `first`, `last` URLs (RFC 5988). Cursor pagination on hot lists
++  `prev`, `first`, `last` URLs. URLs are absolute and use the
--  uses `?cursor=…` and returns the next cursor in the `Link:`
++  instance's configured public base URL. Forward-only feeds emit
++  only `next` / `prev` (no `first` / `last`) when totals are
++  expensive to compute. Cursor pagination on hot lists uses
++  `?cursor=…` and returns the next cursor in the same `Link:`
    header.
  - **Body cap:** request bodies are capped at 256 KiB. Larger
    payloads return `413`.
  - **Rate limits:** every response includes `X-RateLimit-Limit`,
    `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers (Unix
--  timestamp). Exceeding the limit returns `429`.
++  timestamp). Exceeding the limit returns `429` with the canonical
++  error envelope, a `Retry-After` header (seconds), and
++  `X-RateLimit-Remaining: 0`. Defaults: 5000 / hour for PAT
++  callers (keyed by token id) and 60 / hour for anonymous callers
++  (keyed by remote IP). Operators tune via
++  `SHITHUB_RATELIMIT__API__AUTHED_PER_HOUR` and
++  `SHITHUB_RATELIMIT__API__ANON_PER_HOUR`.
++- **Request id:** every response echoes `X-Request-Id`. If the
++  caller sends one (matching `[a-z0-9/:_-]{1,128}`) it's reused;
++  otherwise the server generates a fresh 16-byte hex id. Quote
++  this id in support reports — it correlates against the server
++  logs.
++
++## Capability discovery
++
++`GET /api/v1/meta` is unauthenticated and returns the server's
++version stamp plus a list of feature capability strings. Clients
++use it to gate optional features without trial-and-error:
++
++```json
++{
++  "version": "v0.2.0",
++  "commit": "abc1234",
++  "built_at": "2026-05-12T03:00:00Z",
++  "capabilities": ["pat-auth", "check-runs", "stars", "actions-lifecycle"]
++}
++```
++
++New capability identifiers are appended as feature batches land;
++existing entries are stable.
  ## Versioning