Status: Planned (B5 provider slice)
Updated: May 30, 2026
Official source
- API base/docs: <https://api.harvardartmuseums.org>
Key platform facts (from official docs)
- Base API host: `https://api.harvardartmuseums.org`
- API key required on all requests via `apikey` query parameter.
- JSON response structure includes:
- `info` (pagination + response metadata)
- `records` (result rows)
- `aggregations` (optional analysis block)
- Paging controls:
- `size` default 10, max 100
- `page` for page navigation
- `info.next` / `info.prev` provide full next/prev links
- Errors:
- `401` invalid/missing API key
- `404` resource not found
- IIIF:
- Image API via `baseimageurl`/`primaryimageurl` (IIIF Image API 2.1 style paths)
- Presentation collection: `https://iiif.harvardartmuseums.org/collections/top`
- Manifest base: `https://iiif.harvardartmuseums.org/manifests`
Integration goals
- Add Harvard as a first-class B5 provider through `provider-interface`.
- Preserve canonical Linked Art JSON-LD at storage boundary.
- Respect Harvard operational/terms constraints in adapter and cache policy.
Proposed implementation slice
Adapter
- `src/adapters/harvard.ts`
- profile descriptor
- object/person/exhibition search helpers
- content normalization to `SourceRecord` + `Artwork` DTO boundary
- IIIF image/manifest URL projection helpers
Routes
- `GET /api/harvard/profile`
- `POST /api/harvard/search`
- `POST /api/harvard/object`
- `POST /api/harvard/import`
UI
- add `harvard` source toggle in `/explore`
- preserve source attribution, rights/reuse messaging, and object link-back fields
Env configuration
- `HARVARD_API_BASE` (default: `https://api.harvardartmuseums.org`)
- `HARVARD_API_KEY` (required for live calls)
- `HARVARD_IIIF_MANIFEST_BASE` (default: `https://iiif.harvardartmuseums.org/manifests`)
Operational and terms guardrails
- Respect rate guidance: max 2500 API calls/day.
- Do not cache/store Harvard API content longer than two weeks without explicit permission.
- Use image URLs returned by Harvard APIs (no local image copying).
- Preserve attribution and link-back to Harvard content location.
- Treat provider as non-commercial-content constrained in downstream usage paths.
Implementation policy:
- Centralize request budgeting in provider adapter/service layer.
- Add cache TTL defaults that cannot exceed the two-week policy.
- Surface attribution + source URL fields in all UI entry points.
Standards mapping + tests
Required rounds (minimum): object/provenance/shared-structure + protocol/search rounds.
Required tests (failing-first):
- `tests/adapters/harvard.test.ts`
- `tests/api/harvard/profile.test.ts`
- `tests/api/harvard/search.test.ts`
- `tests/api/harvard/object.test.ts`
- `tests/api/harvard/import.test.ts`
Policy tests:
- API key missing/invalid behavior mapping
- rate-budget guard behavior
- cache TTL guard (`<= 14 days`)
- attribution/link-back field persistence
Protocol checks (B8):
- OPTIONS/CORS behavior on Harvard routes
- response shape conformance
- URI opacity + array-cardinality safety where applicable
Exit criteria
- Adapter + routes + tests green.
- `/explore` can search/import Harvard records.
- PR includes Standards Mapping note with round + fixture anchor coverage.