Open Library's API is a nonprofit treasure — and your dev loop shouldn't be hammering it

Open Library (openlibrary.org) is an Internet Archive project: an open, editable catalog of tens of millions of books, with a free keyless API behind a huge share of "build a book search app" tutorials. It deserves the praise it gets. It is also, operationally, a donation-funded nonprofit — and it behaves like one. While writing this guide (September 2026), roughly 1 in 6 of our calls hung for ~15 seconds and then dropped at the TLS handshake — no HTTP status, no error body, just:

$ curl "https://openlibrary.org/search.json?q=foundation+asimov&limit=5"
curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL in connection to openlibrary.org:443

In a browser that's TypeError: Failed to fetch — the code path your catch block sees least often and your tests exercise never. Minutes later the very same URLs answered in 0.4s. When healthy, searches took 2–5 seconds in our timed runs. And the official docs ask for restraint: 1 request/second for unidentified clients (3/sec if your User-Agent includes contact info), and no bulk downloading — that's what their data dumps are for.

None of this is a complaint. For production book lookups, Open Library is the right choice — cache responses, identify yourself, and consider supporting the Archive. But a hot-reloading dev server that re-fires the search on every keystroke, or a CI matrix hitting it from six parallel workers, is fragile for you and rude to a nonprofit. Point those at a mock with the exact shapes.

The two shape traps your mock must reproduce

Live-verified on real works, because both bite constantly:

1. description is two different types. On /works/OL1168083W.json (Nineteen Eighty-Four) it's a plain string. On /works/OL27448W.json (The Lord of the Rings) it's {"type":"/type/text","value":"…"}. Render code that assumes one shape prints [object Object] or throws on .value — the classic Open Library bug. (Author bio has the same split.)
2. Works don't include author names. /works/…json gives authors:[{"author":{"key":"/authors/OL26320A"}}] — an N+1 fetch per author for the name. Search docs do carry author_name, which is why apps mix both endpoints and inherit both failure modes.

1. Capture real search docs once, mock forever

Pull one real search and host the docs as your own API — records keep every field verbatim (key, cover_i, the author_name array, first_publish_year, all of it):

curl -s "https://openlibrary.org/search.json?q=lord+of+the+rings&limit=20" \
  | jq '{books: .docs}' > db.json

curl -s -X POST "https://mockbird.mockbird.workers.dev/api/projects/import?name=openlibrary-mock" \
  -H 'content-type: application/json' --data-binary @db.json

No signup, no key. The response has your project id and adminKey, plus honest warnings — array fields like author_name are kept verbatim in the records but skipped from the flat field schema. Your copy answers instantly, deterministically, with a query toolkit Open Library's search syntax doesn't map to:

$ curl "https://mockbird.mockbird.workers.dev/m/YOUR_ID/books?title_like=hobbit&select=title,first_publish_year"
[{"id":5,"title":"The Hobbit & The Lord of the Rings [collection/set]","first_publish_year":1979},
 {"id":15,"title":"The Hobbit","first_publish_year":1937}]

$ curl "https://mockbird.mockbird.workers.dev/m/YOUR_ID/books?first_publish_year_gte=2001&select=title,first_publish_year"

$ curl "https://mockbird.mockbird.workers.dev/m/YOUR_ID/books?sortBy=first_publish_year&order=asc&limit=3"

?q= searches whole records including the nested arrays — ?q=tolkien matches on author_name even though it's not in the flat schema. Writes persist: POST /books a record and it's there on the next GET. Free bonuses: /m/YOUR_ID/types.ts generates TypeScript interfaces (?format=zod for Zod), and /graphql serves the same records with typed queries.

2. Reproduce the search envelope

Your frontend reads resp.docs and resp.numFound. Make the mock answer in Open Library's exact search wrapper — set it once as the project default with a response envelope:

curl -X PUT "https://mockbird.mockbird.workers.dev/api/projects/YOUR_ID/settings" \
  -H "x-admin-key: YOUR_ADMIN_KEY" -H 'content-type: application/json' \
  -d '{"envelope":{"numFound":"$total","start":0,"numFoundExact":true,"num_found":"$total","q":"lord of the rings","documentation_url":"https://openlibrary.org/dev/docs/api/search","docs":"$data"}}'

Verified output from a live project while writing this:

$ curl "https://mockbird.mockbird.workers.dev/m/YOUR_ID/books?limit=2&select=title"
{"numFound":20,"start":0,"numFoundExact":true,"num_found":20,
 "q":"lord of the rings","documentation_url":"…",
 "docs":[{"id":1,"title":"The Lord of the Rings"},{"id":2,"title":"The Fellowship of the Ring"}]}

Both spellings (numFound and num_found) included, because the real API sends both. Need a bare array somewhere? ?mock_envelope=none disables it per request.

3. Byte-exact works — with both description shapes

If your code hardcodes /works/…json paths, reproduce them as custom routes. Capture one work of each description shape and serve them back byte-for-byte (we verified both served responses parse-equal to the live API's, and that the envelope from §2 does not touch custom routes):

curl -s "https://openlibrary.org/works/OL27448W.json" > lotr.json      # description is {type,value}
curl -s "https://openlibrary.org/works/OL1168083W.json" > b1984.json   # description is a plain string

jq '{path:"/works/OL27448W.json", body:.}' lotr.json \
  | curl -s -X POST "https://mockbird.mockbird.workers.dev/api/projects/YOUR_ID/routes" \
    -H "x-admin-key: YOUR_ADMIN_KEY" -H 'content-type: application/json' --data-binary @-
jq '{path:"/works/OL1168083W.json", body:.}' b1984.json \
  | curl -s -X POST "https://mockbird.mockbird.workers.dev/api/projects/YOUR_ID/routes" \
    -H "x-admin-key: YOUR_ADMIN_KEY" -H 'content-type: application/json' --data-binary @-

Now one test renders /m/YOUR_ID/works/OL27448W.json and the other /m/YOUR_ID/works/OL1168083W.json — your description-handling code is finally exercised against both real shapes on every CI run, not whenever the right book happens to come up.

4. Order the slowness (and the drop) on demand

The failure modes you met above are exactly what you can now test deterministically:

• Real-world latency: ?mock_delay=3000 is an honest Open Library search. Do your skeletons hold up for 3 seconds without layout shift?
• The connection drop: the TLS-level failure has no HTTP status to simulate — what your app actually exercises is its timeout path. Give your client a 2s timeout (AbortSignal.timeout(2000)) and point it at ?mock_delay=4000: fetch throws with no response object, same as the real drop. We verified curl exits 28 (timed out) on exactly this setup.
• Retry logic: ?mock_seq=503,503,200 fails exactly twice then succeeds — assert your third attempt renders.
• The courtesy budget: ?mock_ratelimit=3 is the 1–3 req/sec etiquette in miniature — three 200s with decrementing x-ratelimit-remaining, then a 429 with a real Retry-After to point your backoff at. More: rate-limit simulation, loading & error states.

5. Honest comparison

The pattern that's fair to everyone: base URL in an env var — Open Library in production behind a cache, your /m/YOUR_ID in .env.test and the dev server. Their servers stop seeing your hot reloads; your CI stops seeing their bad minutes. Current status of the real API: /status/openlibrary. Related: Free Dictionary API, Jikan (MyAnimeList), REST Countries, mock any third-party API.