reference disagrees with spec
Four calls in the published REST reference exist under no spelling in the deployment's own OpenAPI document, which names two of them differently.
- Kind
- The behaviour is defensible and undocumented
- Status
- unreported
- Confirmed
2026-09-04- Evidence
Expected The published reference and the OpenAPI document the deployment serves at /spec.json
describe the same API.
Actual GET /spec.json returns 191452 bytes of OpenAPI v3 advertising 62 operations. Four calls the
reference documents are in it under no spelling:
| the reference documents | the site's spec has |
|---|---|
PUT /entity/{entity}/{record_id}/_revive |
nothing under that path |
POST .../_upload_complete |
nothing under that path |
PATCH /schema/{entity}/fields/{field} |
PUT /schema/<type>/fields/<field> |
PATCH /preferences |
PUT /preferences/update |
The PUT on a schema field was measured working. servers[0].url in the spec ends in /api/v1.1 while
the reference documents /api/v1; a sweep of 20 read-only calls under both prefixes found the same API,
differing only in api_version in the root document and the prefix each echoes in its own links.
Reproduce
curl -sS "$SITE/api/v1/spec.json" -H "Authorization: Bearer $TOKEN" \
| python3 -c 'import json,sys; print("\n".join(sorted(json.load(sys.stdin)["paths"])))'
# No _revive, no _upload_complete. Schema fields and preferences are PUT, not PATCH
Impact A client written from the reference has four calls that do not exist, and two of them are spelled closely enough to look like a typo on the caller's side rather than a documentation error. The prefix mismatch sends anyone comparing the two looking for a version difference that is not there.
Proposed change Correct the four paths in the reference to the spellings the deployment serves, and
say in the reference that /spec.{format} is the authority for a given deployment. No API change is
needed for any of it.