Versioning

Every path starts with /api/v1 on https://rigel.house. The version is the path. The OpenAPI document that describes every operation is at /api/v1/openapi.json, and a raw interactive view of it is at /api/v1/docs. The document's own version field says 0.0.0 and doesn't mean anything yet.

curl https://rigel.house/api/v1/health
# {"ok":true}

A few paths need no sign-in: /api/v1/health, the OpenAPI document and its viewer, and the socket's message schemas at /api/v1/socket-schema.json.

Rigel has one client today, its own web app, and it ships together with the server. While that is true, a name or a shape can change in one release, along with the web app that uses it. If you build on the API now, expect breaking changes. Nothing announces them in advance: there is no version pinning and no changelog yet.

The rule changes when a native app ships. From then on the server keeps accepting the previous app version's requests and commands until that version is retired. Changes to the stored shape follow the same idea in two steps: the new shape is added while the old one keeps working, and only a release later is the old one removed. The sync guide says what a client that mirrors rows should do about that.

Write clients that tolerate additions, because those can arrive at any time:

• New operations, and new optional fields on existing ones.
• New values in an enum. The unit list only grows, and so do error codes.
• New fields in a response, and new columns in pulled rows.
• New message types on the socket. Ignore the ones you don't know.

Branch on an error's code, never on its message. The errors guide lists the envelope.

What happens to a field the API doesn't define depends on the route.

• The file routes reject a query parameter they don't define, and so do a few inventory and meals inputs. The answer is 400 validation_failed, naming the field in details.fields.
• Most commands and queries ignore a field they don't define. A required field that is missing or wrong is always a 400 validation_failed that names it, but a misspelled optional field is dropped without a word.

The operation pages are built on every deploy from the same definitions the API runs: the list of commands and queries, and the OpenAPI document made from it. Every operation that is routed has a page, and a new command appears on its own. Their content comes from the code, so a page cannot describe a field the API doesn't have.

Examples come from three places.

• A command's examples are its test cases, run through the same code the API runs.
• A query's or route's examples are recorded from a sample household, the Okafors, run through the whole API in memory.
• An operation with neither gets an example built from its schema, and the page labels it as built from the schema rather than recorded.

The guides are written by hand, and the build checks them against the code. A guide that names an operation, a guide or an example that doesn't exist fails the build, so a rename can't leave a stale link on a deployed page. The reference describes what is running as of the last deploy.