Start with a domain model you own
A public provider response is an input, not the permanent shape of your product. Define internal resources for works, editions, people or organizations, contributions, identifiers, covers, subjects, sources, and claims. Provider adapters translate into that model. When a source changes or a licensed feed replaces an open source, client URLs and stored IDs remain stable.
A work groups the conceptual creation. An edition carries publication-specific facts such as publisher, date, language, format, page count, and ISBN. A cover is media. An offer is commerce. A scan is a digitized artifact. A summary is generated enrichment. This separation prevents a current price from being mistaken for book metadata or an AI synopsis from replacing publisher copy.
Core endpoint families
Search
GET /v1/books with query, author, subject, language, date, format, identifier, pagination, sorting, and field projection.
Exact lookup
GET /v1/editions/by-isbn/{isbn} with normalized input, validation, not-found, ambiguity, and source provenance.
Canonical detail
GET /v1/works/{id} and /editions/{id} with optional expansions for contributors, covers, offers, scans, and summaries.
Batch jobs
POST /v1/catalog-jobs for bounded imports with idempotency, per-row status, progress, and downloadable results.
Search should explain matches
Normalize punctuation, Unicode, whitespace, contributor order, and identifier formatting. Rank exact ISBN matches above fuzzy text matches. Return match reasons such as exact identifier, title phrase, author agreement, or subject match. Edition-aware results should show format, language, publisher, and date so a user can choose the right publication rather than selecting the first familiar cover.
Facets can include contributor, language, subject, publication decade, format, publisher, and access type. Search totals may be approximate. For bulk enumeration, use feeds or export jobs rather than pretending interactive search is a complete global catalog.
Provenance and conflict are response features
Sources disagree. Preserve alternative claims and apply documented selection rules. A response can return selected fields with a compact source map, while review tools retain every raw claim. Timestamps should distinguish API response time from source retrieval time. Generated and inferred values require their own method, model, or rule metadata.
Errors clients can act on
Use stable machine codes for invalid identifiers, no match, ambiguous match, unsupported expansion, rate limit, upstream timeout, partial enrichment, and policy rejection. Translate provider-specific failures at the adapter boundary. Include a request ID and retry guidance where appropriate. A valid ISBN with no selected-source match is different from a malformed ISBN.
Production checklist
- Internal IDs do not depend on one provider.
- Works and editions are distinct.
- Identifiers are typed and scoped.
- Field-level provenance survives reconciliation.
- Search and detail have different projections.
- Batch work is idempotent and resumable.
- Freshness policy varies by resource.
- Contract fixtures include missing and conflicting records.