The Quirks Catalog¶
The Sierra REST API behaves in ways its documentation doesn't always mention. This catalog records the non-obvious behaviors we've hit in real work, so you can plan for them instead of discovering them mid-batch.
How to read these entries¶
Every quirk is a card with the same four lines:
- Behavior — what actually happens.
- Type — Bug-or-quirk, By design, or Data quality.
- How to handle — the workaround or rule of thumb.
- How we know — the empirical evidence behind the claim.
Verify on your own deployment
These behaviors were observed on specific Sierra deployments (production and test). Versions and configuration differ between libraries. Treat each entry as a strong hypothesis to confirm on your system — and see Discover quirks yourself.
Provenance: patron-record heavy (bib/harvest coverage growing)
Most of the write/side-effect knowledge came from patron-record projects, so the catalog still leans that way. The Change polling page begins filling the bib/harvest gap (range queries, deletion polling, pagination) from a production bib-harvest project; item- and order-specific quirks are still under-represented. Found one? Send it in.
Quick reference¶
| Quirk | Type | Page |
|---|---|---|
PUT phones is additive, not replacement |
Bug-or-quirk | Write semantics |
PUT varFields replaces per fieldTag group (not whole-array, not merge) |
By design | Write semantics |
A successful PUT returns 204, not 200 |
By design | Write semantics |
fixedFields PUT requires label beside value |
By design | Write semantics |
| PUT rejects ~9 read-only top-level fields | By design | Write semantics |
Empty content deletes a patron varField; blanks item/bib ones |
By design | Write semantics |
emails/phones/addresses/names are derived projections |
By design | Write semantics |
PUT bumps four fixedFields timestamps/counters, no opt-out |
By design | Side effects |
| GET never bumps; a failed PUT (400) never bumps | By design | Side effects |
| Revisions counter: +2 per REST PUT vs +1 per Desktop save | Bug-or-quirk | Side effects |
fields=, returns all fields; allow-lists may 400 — but deletedDate is not in it |
By design | Reads & IDs |
isRequestable costs ~56× more per record than any other bib field |
By design | Reads & IDs |
The item-type REST field is itemType, not itype |
By design | Reads & IDs |
| "Ghost records": GET 200 but PUT 404 | Bug-or-quirk | Reads & IDs |
API id = record_num, not the DB primary key |
By design | Reads & IDs |
| Multiple values packed into one varField | Data quality | Reads & IDs |
| varField content length ceiling is ≥ 8000 chars | By design | Reads & IDs |
An enumerated id list silently returns only the default page of 50 unless you set limit |
By design | Reads & IDs |
Zero-match range query may 404 (code 107) — and query shapes disagree |
Bug-or-quirk | Change polling |
deletedDate is date-only; updatedDate is a full timestamp |
By design | Change polling |
GET bibs returns entries ascending by id (keyset-paginable) |
By design | Change polling |
updatedDate + id range filters AND together in one query |
By design | Change polling |
List responses cap at ~2000; detect end by a short page, not total |
By design | Change polling |
deleted=false hides server-deleted records (they vanish from polls) |
By design | Change polling |
fields=, returns 500 on a deleted=true query — name the fields |
Bug-or-quirk | Change polling |
MARC records cap at 99,999 bytes — bibs with many items lose their 945 tail |
By design | MARC export |
Truncation shows up only as errors in the MarcSummary; the MARC parses clean |
Bug-or-quirk | MARC export |
Bulk bibs/marc is binary-only; bibs/{id}/marc and GET bibs' marc/varFields are ceiling-free but carry no 945 |
By design | MARC export |
suppressed is a read-only boolean on bibs and items |
By design | Suppression |
suppressed=true filters; suppressed records are otherwise returned inline |
By design | Suppression |
Suppression rides in the MARC export — bib 998$e, item 945$o |
By design | Suppression |
items?deleted=false returns only the host's own (campus_code='') records |
By design | Scoped records |
record_num is non-unique in record_metadata (one row per scope) |
By design | Scoped records |
validate caseSensitivity defaults to true — rejects mixed-case identifiers |
By design | Patron validation |
validate checks only the first 8 characters of the PIN |
Bug-or-quirk | Patron validation |
Discovering quirks yourself¶
You don't have to take these on faith — every entry is a hypothesis you can confirm on your own deployment with safe, read-mostly probes. See Discovering quirks yourself for the method.