API Conventions

One page of rules shared by every module, so the per-module docs stay short.

Base URLs#

• Backend origin: https://shanebackend-production.up.railway.app
• https://shanejli.com/api/* rewrites to the same backend (afterFiles rewrite), so relative /api/... URLs work from the site's own pages.

Errors#

Every error is JSON with a top-level error string — no exceptions. Unhandled throws return 500 {"error":"Internal Server Error"}; an unmatched route returns 404 {"error":"Not Found","path":"/api/nope"}.

Validation failures (bad params, query, or body) return 400 and add a structured details array alongside the summary:

{
  "error": "Validation failed: limit: Expected number, received nan; cursor: YYYY-MM-DD",
  "details": [
    { "path": "limit", "message": "Expected number, received nan" },
    { "path": "cursor", "message": "YYYY-MM-DD" }
  ]
}

details[].path is the dot-joined field path (notes.0.text for array elements) and is omitted for object-level errors. error folds the first 5 issues into one readable line and appends (+N more); details always carries every issue. Read details for field-level form errors, error when you just need one message to show.

Auth posture#

• Missing/invalid token on a protected route: 401.
• PAT lacking the required scope: 403 Token missing required scope: <scope>.
• A row that exists but is not yours: usually 404, not 403 (deliberately indistinct; loans is the exception and 403s).

Wire format#

• JSON bodies. Request field names are camelCase in most modules; the journal and comment surfaces use snake_case for multi-word request fields (parent_comment_id, base_version_num, target_version_num). Responses are camelCase everywhere.
• Dates that key resources are YYYY-MM-DD strings, validated as real calendar dates (2026-02-30 is a 400, not a 500).
• Ids are UUIDs. Any case is accepted on input (Swift's uuidString is uppercase) and responses always return lowercase, so compare ids case-insensitively or lowercase them first.
• Free-text fields are trimmed before validation; whitespace-only input is a 400.
• A NUL byte is a 400 everywhere: %00 anywhere in the URL (details[].path is url), or \u0000 in any string or key of a JSON body (details[].path names the field), or in the file text, title or filename of a multipart trip upload (details[].path is html, title or filename). Postgres cannot store it, and before SHAN-553 (SHAN-602 for multipart trips) it came back as a 500.

Text search#

Four endpoints take a free-text term: journal entries and blog posts as q, knowledge entries and vocabulary words as search. All four are case-insensitive substring matches, and the term is taken literally: send it raw.

That last part is worth stating because it stopped being true twice. The match runs on Postgres ILIKE, where % and _ are pattern syntax rather than characters, so a term wrapped straight into %...% turns _ into "any one character" and % into "any run of characters". Until SHAN-545 the two vocabulary surfaces did exactly that, and ?search=_ returned the entire table (48 of 48 rows) instead of the rows containing an underscore, a plausible query against a word list full of snake_case and __init__. All four now escape the term server-side.

So: do not escape the term yourself. Sending snake\_case searches for a literal backslash. A term that finds nothing finds nothing; there is no pattern syntax to reach for.

Pagination#

Most modules paginate by keyset, newest-first, via limit (1 to 100) and cursor. Treat cursor as opaque: read nextCursor off a response and send it back verbatim. Null means done.

The cursor value differs by module. The journal entries cursor is the last entry's DATE (YYYY-MM-DD). Blog and journal version history key on the version number, which is bounded to 1..2147483647 (the range of the int4 column behind it); a larger value is a 400, not a 500 from Postgres. Everything else — trips, loans, tea, scoreboard matches, courses, rng history, journal activity, blog posts — keys on a timestamp, and since SHAN-513 that cursor carries the boundary row's id too, as <iso-timestamp>_<row-id>:

2026-05-24T21:32:37.484Z_5269f919-dfae-4d7a-9320-0036f2554ab0

The id half is not decoration. A timestamp alone is not unique and the ISO form is only millisecond-precise, while the stored column is microsecond-precise, so a cursor built from the timestamp alone could skip rows that shared the boundary row's millisecond — silently, with a 200 and a short page. The id makes the sort key total and lets the server read the boundary row's exact stored timestamp back.

Cursors minted before this change (a bare ISO timestamp, no _) are still accepted, so nothing in flight broke. A malformed cursor is a 400, never a silent reset to page 1.

Knowledge and vocabulary are the exception: they page by limit (1 to 500, default 100) and offset, and echo { total, limit, offset } back so you can compute the page count up front. They have no nextCursor, so you are done when offset + limit >= total. offset runs 0 to 1,000,000 — 10,000 pages at the default size of 100, 2,000 at the 500 maximum, far past any list here — and anything above that is a 400. Before SHAN-529 it had no ceiling, so a value Postgres could not parse as a bigint (1e30, 9223372036854775807) reached the query and came back as a 500.

Offset paging needs the same total sort key for the same reason, and since SHAN-515 it has one: both routes order by (created_at DESC, id DESC). Each page is a separate query, and Postgres promises nothing about how rows that tie on the sort key fall between two of them, so without the id half a walk over offset=0, 100, 200 … could return one entry on two pages and never return another. Offset is still only stable against a still list: rows written between your requests shift everything after them, so an ingest running alongside a long walk can repeat a row. Re-read from offset=0 if you need a consistent snapshot.

Caching and conditional GET#

Every 200 JSON response to a GET carries a weak validator, ETag: W/"...", plus Cache-Control: private, no-cache. Send the validator back as If-None-Match on the next poll and an unchanged resource answers 304 with an empty body instead of re-sending the payload:

BASE=https://shanebackend-production.up.railway.app
ETAG=$(curl -sD - -o /dev/null "$BASE/api/journal/entries" | grep -i '^etag:' | cut -d' ' -f2- | tr -d '\r')
curl -s -o /dev/null -w '%{http_code} %{size_download}' -H "If-None-Match: $ETAG" "$BASE/api/journal/entries"
# 304 0

• The tag is derived from the response body, so any change to the data changes the tag.
• It is weak because gzip is applied at the edge rather than by the API, so identical data ships as more than one byte sequence. Weak comparison is what If-None-Match uses anyway, so 304s still work.
• no-cache means "you may store it, but revalidate before reuse". It does not mean "do not store". private is there because responses vary by Authorization while Vary does not list it, so a shared cache must never reuse one across users.
• A comma-separated If-None-Match list and * both work, and "abc" matches W/"abc".
• Image routes such as /api/journal/images/:id opt out. They are immutable and already ship Cache-Control: public, max-age=31536000, immutable.
• In a browser, read the header off response.headers.get("ETag"). It is listed in Access-Control-Expose-Headers, without which fetch() cannot see it.

Optimistic concurrency (If-Match)#

Racy journal mutations (revert, suggestion approve) and blog body edits require an If-Match header carrying the current version number as a plain integer (from GET /api/journal/entries/:date or GET /api/blog/posts/:slug, field currentVersionNum).

• Missing header: 428
• Non-numeric: 400
• Stale: 409 with {"error":"Version conflict","currentVersionNum":<latest>} so you can rebase and retry.

From a browser, send X-If-Match instead#

X-If-Match is accepted everywhere If-Match is, and browser code must use it. Requests from shanejli.com are same-origin and ride a rewrite through Vercel's edge, which evaluates a real If-Match against the response's ETag. Every 200 JSON response here carries a weak validator, and a weak validator can never satisfy If-Match, which requires strong comparison, so the edge replaced the origin's 200 with 412 PRECONDITION_FAILED after the write had committed. A save that succeeded was reported as a failure, and the retry wrote it a second time. Error responses carry no ETag, which is why the 409 and 428 paths were unaffected (SHAN-487 for the blog, SHAN-489 for the journal). As measured on 2026-09-13 the edge applies this to PATCH and currently lets POST through; send X-If-Match on every conditional write rather than depending on that.

If you call the API directly (a PAT plus curl against the Railway origin), If-Match is fine and remains the documented header. If-Match wins if you send both.

Rate limits#

Per-PAT rolling 60 second buckets (JWT browser sessions bypass); see the bucket table in Auth and Tokens. 429 responses carry Retry-After.

CORS#

Allowed request headers are Content-Type, Authorization, If-Match, X-If-Match, If-None-Match, X-Tea-Pin. ETag is the one exposed response header. A new custom header needs a backend change; the symptom of forgetting is a browser-only "Failed to fetch".