{"id":"providers/vanda-collections-api","relativePath":"providers/vanda-collections-api.md","title":"Victoria and Albert Museum (V&A) Collections API Integration Plan","markdown":"# Victoria and Albert Museum (V&A) Collections API Integration Plan\n\nStatus: Planned (B5 provider slice)  \nUpdated: May 30, 2026\n\n## Official source\n\n- Developer docs: <https://developers.vam.ac.uk/>\n- API base: <https://api.vam.ac.uk/v2/>\n\n## Key platform facts (from official docs)\n\n- API v2 provides JSON and CSV outputs.\n- Core search endpoint pattern: `GET /v2/objects/search`\n- Supports rich searching/filtering/restriction/result controls (identifier filters, keyword filters, random, search mode).\n- Response commonly includes:\n  - `info` (including `record_count`, pagination metadata)\n  - `records`\n- V&A supports IIIF:\n  - Image API base pattern via framemark URLs\n  - Presentation manifest URLs under `https://iiif.vam.ac.uk/collections/{objectidentifier}/manifest.json`\n- Typical image metadata fields in search records:\n  - `_primaryImageId`\n  - `_images._iiif_image_base_url`\n  - `_images._iiif_presentation_url`\n\n## Integration goals\n\n- Add V&A as a first-class B5 provider through `provider-interface`.\n- Normalize V&A object/search responses into canonical Linked Art JSON-LD boundary records.\n- Preserve IIIF image/presentation references for downstream deep-zoom/presentation features.\n\n## Proposed implementation slice\n\n### Adapter\n\n- `src/adapters/vanda.ts`\n  - profile descriptor\n  - identifier + keyword filter request helpers\n  - object/result normalization to `SourceRecord` + `Artwork` DTO boundary\n  - IIIF projection helpers (`info.json`, image base URL, presentation manifest URL)\n\n### Routes\n\n- `GET /api/vanda/profile`\n- `POST /api/vanda/search`\n- `POST /api/vanda/object`\n- `POST /api/vanda/import`\n\n### UI\n\n- add `vanda` source toggle in `/explore`\n- preserve attribution/reuse indicators and IIIF manifest links in detail views\n\n## Env configuration\n\n- `VANDA_API_BASE` (default: `https://api.vam.ac.uk/v2`)\n- `VANDA_MAX_PAGE_SIZE` (default: `100`, hard cap = 100)\n- `VANDA_IIIF_IMAGE_BASE` (default: `https://framemark.vam.ac.uk/collections`)\n- `VANDA_IIIF_PRESENTATION_BASE` (default: `https://iiif.vam.ac.uk/collections`)\n\n## Operational and terms guardrails\n\n- For bulk data workflows, API is not preferred; use dataset/export collaboration where appropriate.\n- Respect V&A terms of use for data/images and cite V&A in downstream outputs.\n- Preserve source image URLs from provider (no local image copying as default policy unless rights/terms explicitly permit).\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/vanda.test.ts`\n- `tests/api/vanda/profile.test.ts`\n- `tests/api/vanda/search.test.ts`\n- `tests/api/vanda/object.test.ts`\n- `tests/api/vanda/import.test.ts`\n\nProvider-specific conformance tests:\n\n- identifier filter path coverage (`id_material`, etc.) and keyword filter path coverage (`kw_*`)\n- search mode handling (`broad` vs `narrow`) where supported by route\n- IIIF field extraction and URL normalization\n\nProtocol checks (B8):\n\n- OPTIONS/CORS behavior on V&A 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 V&A 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":"<h1 id=\"victoria-and-albert-museum-v-a-collections-api-integration-plan\">Victoria and Albert Museum (V&amp;A) Collections API Integration Plan</h1>\n<p>Status: Planned (B5 provider slice)  </p>\n<p>Updated: May 30, 2026</p>\n<h2 id=\"official-source\">Official source</h2>\n<ul><li>Developer docs: &lt;https://developers.vam.ac.uk/&gt;</li><li>API base: &lt;https://api.vam.ac.uk/v2/&gt;</li></ul>\n<h2 id=\"key-platform-facts-from-official-docs\">Key platform facts (from official docs)</h2>\n<ul><li>API v2 provides JSON and CSV outputs.</li><li>Core search endpoint pattern: `GET /v2/objects/search`</li><li>Supports rich searching/filtering/restriction/result controls (identifier filters, keyword filters, random, search mode).</li><li>Response commonly includes:</li><li>`info` (including `record_count`, pagination metadata)</li><li>`records`</li><li>V&amp;A supports IIIF:</li><li>Image API base pattern via framemark URLs</li><li>Presentation manifest URLs under `https://iiif.vam.ac.uk/collections/{objectidentifier}/manifest.json`</li><li>Typical image metadata fields in search records:</li><li>`_primaryImageId`</li><li>`_images._iiif_image_base_url`</li><li>`_images._iiif_presentation_url`</li></ul>\n<h2 id=\"integration-goals\">Integration goals</h2>\n<ul><li>Add V&amp;A as a first-class B5 provider through `provider-interface`.</li><li>Normalize V&amp;A object/search responses into canonical Linked Art JSON-LD boundary records.</li><li>Preserve IIIF image/presentation references for downstream deep-zoom/presentation features.</li></ul>\n<h2 id=\"proposed-implementation-slice\">Proposed implementation slice</h2>\n<h3 id=\"adapter\">Adapter</h3>\n<ul><li>`src/adapters/vanda.ts`</li><li>profile descriptor</li><li>identifier + keyword filter request helpers</li><li>object/result normalization to `SourceRecord` + `Artwork` DTO boundary</li><li>IIIF projection helpers (`info.json`, image base URL, presentation manifest URL)</li></ul>\n<h3 id=\"routes\">Routes</h3>\n<ul><li>`GET /api/vanda/profile`</li><li>`POST /api/vanda/search`</li><li>`POST /api/vanda/object`</li><li>`POST /api/vanda/import`</li></ul>\n<h3 id=\"ui\">UI</h3>\n<ul><li>add `vanda` source toggle in `/explore`</li><li>preserve attribution/reuse indicators and IIIF manifest links in detail views</li></ul>\n<h2 id=\"env-configuration\">Env configuration</h2>\n<ul><li>`VANDA_API_BASE` (default: `https://api.vam.ac.uk/v2`)</li><li>`VANDA_MAX_PAGE_SIZE` (default: `100`, hard cap = 100)</li><li>`VANDA_IIIF_IMAGE_BASE` (default: `https://framemark.vam.ac.uk/collections`)</li><li>`VANDA_IIIF_PRESENTATION_BASE` (default: `https://iiif.vam.ac.uk/collections`)</li></ul>\n<h2 id=\"operational-and-terms-guardrails\">Operational and terms guardrails</h2>\n<ul><li>For bulk data workflows, API is not preferred; use dataset/export collaboration where appropriate.</li><li>Respect V&amp;A terms of use for data/images and cite V&amp;A in downstream outputs.</li><li>Preserve source image URLs from provider (no local image copying as default policy unless rights/terms explicitly permit).</li></ul>\n<h2 id=\"standards-mapping-tests\">Standards mapping + tests</h2>\n<p>Required rounds (minimum): object/provenance/shared-structure + protocol/search rounds.</p>\n<p>Required tests (failing-first):</p>\n<ul><li>`tests/adapters/vanda.test.ts`</li><li>`tests/api/vanda/profile.test.ts`</li><li>`tests/api/vanda/search.test.ts`</li><li>`tests/api/vanda/object.test.ts`</li><li>`tests/api/vanda/import.test.ts`</li></ul>\n<p>Provider-specific conformance tests:</p>\n<ul><li>identifier filter path coverage (`id_material`, etc.) and keyword filter path coverage (`kw_*`)</li><li>search mode handling (`broad` vs `narrow`) where supported by route</li><li>IIIF field extraction and URL normalization</li></ul>\n<p>Protocol checks (B8):</p>\n<ul><li>OPTIONS/CORS behavior on V&amp;A routes</li><li>response shape conformance</li><li>URI opacity + array-cardinality safety where applicable</li></ul>\n<h2 id=\"exit-criteria\">Exit criteria</h2>\n<ul><li>Adapter + routes + tests green.</li><li>`/explore` can search/import V&amp;A records.</li><li>PR includes Standards Mapping note with round + fixture anchor coverage.</li></ul>","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"755d939722330e65458ef733263979252d5a99b5dfe096b58dd6b543836a099c","checksumPrefix":"755d93972233","anchorCount":11,"lineCount":97,"rawUrl":"/api/docs/content?path=providers%2Fvanda-collections-api.md","htmlUrl":"/docs?doc=providers%2Fvanda-collections-api.md","apiUrl":"/api/docs/content?path=providers%2Fvanda-collections-api.md"}