API_POLICIES.md: a value in an API response is never a labelled string #137

New Issue

2026-10-27T18:40:04+01:00

clawbot commented

2026-10-27 18:40:04 +01:00

sneak, on sneak/routewatch#199 (27 October 2026):

Strings with labels should never be used as values in api responses. If it's
a native type then put the value in the field name (e.g. _ms).

Have the SDLC top manager codify this into a policy for all APIs we build.

and
(sneak/routewatch#199 (comment)):

in the prompts repo we want an API_POLICIES.md alongside the styleguides

The case that prompted it: routewatch answered
"execution_time": "0 ms", a string holding a number and its unit. The rule
makes that "execution_time_ms": 0, a number, with the unit in the field name.

Definition of done:

API_POLICIES.md exists at the root of this repo, beside
CODE_STYLEGUIDE.md and the language styleguides, on next, through one
reviewed PR.
It states this rule, and only rules sneak has given: an API response never
carries a value as a string with a label or unit in it. A value of a native
type is sent as that type, and its unit goes in the field name, for example
_ms. One short example shows the wrong form and the right one.
The places in this repo that list the policy and styleguide files (the README
and anything else that names them) mention API_POLICIES.md, so repos that
vendor the policies pick it up.

Model: opus-5-5

sneak, on https://git.eeqj.de/sneak/routewatch/issues/199 (27 October 2026): > Strings with labels should never be used as values in api responses. If it's > a native type then put the value in the field name (e.g. \_ms). > > Have the SDLC top manager codify this into a policy for all APIs we build. and (https://git.eeqj.de/sneak/routewatch/issues/199#issuecomment-159403): > in the prompts repo we want an API_POLICIES.md alongside the styleguides The case that prompted it: routewatch answered `"execution_time": "0 ms"`, a string holding a number and its unit. The rule makes that `"execution_time_ms": 0`, a number, with the unit in the field name. Definition of done: - `API_POLICIES.md` exists at the root of this repo, beside `CODE_STYLEGUIDE.md` and the language styleguides, on `next`, through one reviewed PR. - It states this rule, and only rules sneak has given: an API response never carries a value as a string with a label or unit in it. A value of a native type is sent as that type, and its unit goes in the field name, for example `_ms`. One short example shows the wrong form and the right one. - The places in this repo that list the policy and styleguide files (the README and anything else that names them) mention `API_POLICIES.md`, so repos that vendor the policies pick it up. Model: opus-5-5

clawbot commented

2026-10-27 18:41:22 +01:00

Plan, one PR to next:

New file prompts/API_POLICIES.md, with title: API Policies and last_modified front matter like the other cross-project documents. The styleguides live in prompts/, not the repo root, so "beside the styleguides" (sneak's words) puts it there; the root of the repo holds only this repo's own copy of REPO_POLICIES.md.
It states the one rule from the issue and one wrong-and-right example ("execution_time": "0 ms" against "execution_time_ms": 0). Nothing else.
Named where the repo lists its policy and style documents: the list at the top of prompts/REPO_POLICIES.md (its root copy kept identical, last_modified bumped in both) and the two code-style commands in README.md.
TODO.md gets a Completed Steps line.

Model: opus-5-5

Plan, one PR to `next`: - New file `prompts/API_POLICIES.md`, with `title: API Policies` and `last_modified` front matter like the other cross-project documents. The styleguides live in `prompts/`, not the repo root, so "beside the styleguides" (sneak's words) puts it there; the root of the repo holds only this repo's own copy of `REPO_POLICIES.md`. - It states the one rule from the issue and one wrong-and-right example (`"execution_time": "0 ms"` against `"execution_time_ms": 0`). Nothing else. - Named where the repo lists its policy and style documents: the list at the top of `prompts/REPO_POLICIES.md` (its root copy kept identical, `last_modified` bumped in both) and the two code-style commands in `README.md`. - `TODO.md` gets a Completed Steps line. Model: opus-5-5

clawbot referenced this issue from a commit

2026-10-27 18:44:21 +01:00

Add API_POLICIES.md (closes #137)

clawbot referenced a pull request that will close this issue

2026-10-27 18:44:34 +01:00

Add API_POLICIES.md (closes #137) #138

clawbot closed this issue

2026-10-27 18:49:49 +01:00

clawbot referenced this issue from a commit

2026-10-27 18:49:50 +01:00

Add API_POLICIES.md (closes #137)

Sign in to join this conversation.