API Documentation

Discovery

Hudson Street Library implements RFC 9727 for API discovery. You can discover the available APIs in two ways:

Well-Known URI

GET https://hudsonstreetlibrary.com/.well-known/api-catalog

Link Relations

Each HTML page includes this link element:

<link rel="api-catalog" type="application/linkset+json" href="/.well-known/api-catalog">

Note: HTTP Link headers are not available because GitHub Pages does not support custom response headers. The well-known URI and the HTML link element work.

Available APIs

Full Catalog JSON

https://hudsonstreetlibrary.com/data/books.json

This endpoint returns the complete published catalog of 2828 book records, regenerated on every deployment.

Each record carries cover_url alongside the catalogue's own image_url. It is checked against the published files, so it always resolves and is empty only where the library holds no cover.

Format: application/json

Schema: /schemas/book-collection/

Example:

curl https://hudsonstreetlibrary.com/data/books.json | jq '.[0]'

CSV Export

https://hudsonstreetlibrary.com/cms/data/books.csv

This endpoint returns the art wing as CSV. Each record has 37 columns.

Format: text/csv

Schema: /schemas/book-csv/

Example:

curl https://hudsonstreetlibrary.com/cms/data/books.csv | head -5

Every wing:

https://hudsonstreetlibrary.com/cms/data/catalog.csv

The same 37 columns with a 38th, collection, naming the wing each record belongs to. This is the file the catalogue page itself reads.

Collections Metadata

https://hudsonstreetlibrary.com/cms/data/libraryCollections.json

This endpoint returns the thematic collection groupings.

Format: application/json

Schema: /schemas/collections/

Example:

curl https://hudsonstreetlibrary.com/cms/data/libraryCollections.json | jq '.'

Rate Limits & Usage

GitHub Pages serves all endpoints as static files. No rate limits apply beyond the standard GitHub CDN throttling. When the library adds new books, the next deployment updates the data.

CORS: All endpoints support cross-origin requests.

Caching: GitHub Pages serves the files with standard HTTP cache headers. The catalog usually updates weekly.

Standards Compliance

Questions?

To ask a question about the API or to report a problem, open an issue on the project repository.