`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`,
 -  `first`, `last` URLs (RFC 5988). Cursor pagination on hot lists
 -  uses `?cursor=…` and returns the next cursor in the `Link:`
 +  max 100) and return an RFC 8288 `Link:` header with `next`,
 +  `prev`, `first`, `last` URLs. URLs are absolute and use the
 +  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