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

Harvard Art Museums API Integration Plan

\n

Status: Planned (B5 provider slice)

\n

Updated: May 30, 2026

\n

Official source

\n\n

Key platform facts (from official docs)

\n\n

Integration goals

\n\n

Proposed implementation slice

\n

Adapter

\n\n

Routes

\n\n

UI

\n\n

Env configuration

\n\n

Operational and terms guardrails

\n\n

Implementation policy:

\n\n

Standards mapping + tests

\n

Required rounds (minimum): object/provenance/shared-structure + protocol/search rounds.

\n

Required tests (failing-first):

\n\n

Policy tests:

\n\n

Protocol checks (B8):

\n\n

Exit criteria

\n","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"fa8b980154f594b11288f8f782de47730a170624ca1f87fac89bef8b0c10faef","checksumPrefix":"fa8b980154f5","anchorCount":11,"lineCount":108,"rawUrl":"/api/docs/content?path=providers%2Fharvard-art-museums.md","htmlUrl":"/docs?doc=providers%2Fharvard-art-museums.md","apiUrl":"/api/docs/content?path=providers%2Fharvard-art-museums.md"}