API design choices for a desktop app

The Tokori HTTP API runs on localhost, behind a bearer token that lives at ~/.tokori/api-token. It looks REST-ish. Most of the conventions came from "what would a developer expect?" — a few came from "what would actively annoy them?" A short tour.

What we kept from REST

• Resource-oriented URLs. /v1/workspaces/:id/vocab, not /v1/getVocabFor?ws=.... People read URLs out loud.
• HTTP verbs do what they say. GET is safe. POST creates. PATCH is partial. DELETE deletes. We don't redefine them.
• Versioned root. Everything lives under /v1. When we break compatibility, it's a new prefix, not a silent shape change.
• Standard status codes. 401 means "wrong key", 403 means "right key, wrong permission", 404 means "not here", 422 means "validation". One pattern across the whole surface.

What we ignored

• HATEOAS. Nobody writes clients that traverse hypermedia. The docs are the entry point.
• PUT for full-replace. We rarely needed it. PATCH does almost every update we have.
• Nested representations. By default, list endpoints don't embed children. You opt in with ?include=variants when you actually want them. That keeps the common case cheap.

Choices specific to "this lives on localhost"

• No OAuth. A single bearer token, generated locally, rotatable with one CLI command. There's no remote service to log into.
• CORS allows loopback by default. Browser extensions and local web tools should "just work". The token gates anything malicious.
• Read-only mode is a flag, not a separate token. ?readonly=1 on any request. Useful for piping data into tools you don't fully trust.
• SSE for streaming, not WebSockets. Same direction, fewer moving parts, works through every reverse proxy. Chat deltas come out as text/event-stream.

Errors are an envelope, not a status code

Every error returns the same shape: { error: { code, message, field?, request_id } }. The status code communicates the kind, the code string is what your client matches on. Codes are namespaced (vocab.duplicate_word, chat.upstream_error) and stable across patch releases. That makes switch blocks in client code possible without grepping bodies.

Pagination is cursor-based, always

Lists return { data, next_cursor? }. Cursors are opaque base64 strings — clients should not try to parse them. We chose cursors over offsets because vocab lists grow and resort, and offset-pagination would visibly skip rows when something between pages got deleted mid-walk.

What we still don't know

We don't yet have a great answer for batch writes. Adding 5,000 vocab entries means 5,000 round-trips today. That's fine on localhost (microseconds each), but inelegant. A future POST /v1/workspaces/:id/vocab/batch might happen if anyone asks.

The full reference lives in the main Tokori repo on GitHub. Open an issue there if anything looks wrong, surprising, or missing.