Smithsonian Open Access Integration Plan

Status: Landed + constraint-hardened (B5 provider slice)

Updated: May 30, 2026

Official sources

• API docs landing: <https://api.si.edu/openaccess/docs/>
• API key signup: <https://api.data.gov/signup/>
• Open Access program overview: <https://www.si.edu/openaccess>

Key platform facts (from official docs)

• Smithsonian Open Access API requires an `api_key` for endpoint access.
• Core endpoints:
• `GET /openaccess/api/v1.0/search`
• `GET /openaccess/api/v1.0/category/:cat/search`
• `GET /openaccess/api/v1.0/content/:id`
• `GET /openaccess/api/v1.0/terms/:category`
• `GET /openaccess/api/v1.0/stats`
• Search paging:
• `start` (offset)
• `rows` (1..1000, default 10)
• `sort`: `relevancy|id|newest|updated|random`
• Route validation keeps `rowGroup` explicit and enum-limited to `objects|archives`.
• Route validation keeps `category` explicit and enum-limited to official category paths.

Integration goals

• Add Smithsonian as a first-class B5 provider under `provider-interface`.
• Preserve canonical Linked Art JSON-LD at storage boundary (`SourceRecord` + `_source.raw`).
• Keep API-key handling secure (env-only, no logging, no persistence).

Proposed implementation slice

Adapter (implemented)

• `src/adapters/smithsonian.ts`
• profile descriptor
• search request builder (`q/start/rows/sort/type/row_group`)
• content fetch by `id/url`
• normalizer into project record/artwork boundaries

Routes (implemented)

• `GET /api/smithsonian/profile`
• `POST /api/smithsonian/search`
• `POST /api/smithsonian/content`
• `POST /api/smithsonian/import`

UI (implemented)

• add `smithsonian` source toggle in `/explore`
• provider attribution + rights/reuse display on results/details

Env configuration

• `SMITHSONIAN_API_BASE` (default: `https://api.si.edu/openaccess/api/v1.0`)
• `SMITHSONIAN_API_KEY` (required for live endpoint calls)

Security requirements

• Never commit/share `SMITHSONIAN_API_KEY`.
• Never emit the key in logs or error responses.
• Keep outbound calls server-side only (no client-exposed key).

Standards mapping + tests

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

Required tests (failing-first):

• `tests/adapters/smithsonian.test.ts`
• `tests/api/smithsonian/profile.test.ts`
• `tests/api/smithsonian/search.test.ts`
• `tests/api/smithsonian/content.test.ts`
• `tests/api/smithsonian/import.test.ts`

Protocol checks (B8):

• OPTIONS/CORS behavior on new routes
• response shape conformance
• URI opacity + array-cardinality safety where applicable

Exit criteria

• Adapter + routes + tests green.
• `/explore` can search/import Smithsonian records.
• PR includes Standards Mapping note with round + fixture anchor coverage.

Constraint hardening notes

• `SMITHSONIAN_API_KEY` is required for search/content/import fetches to Smithsonian endpoints.
• `/api/smithsonian/search` route-level schema validates official pagination fields:
• `start` integer `>= 0`
• `rows` integer `1..1000`
• Backward-compatible aliases (`offset`/`limit`) remain accepted for older internal callers, but `start`/`rows` are canonical.