Skip to main content

The API reference page

The Norway Data API navbar link opens /api-reference, an interactive API reference rendered by Scalar. The API itself, its OpenAPI spec, its tests, and its docs live in their own repo, cedar-ave/norway-data-api, and deploy to their own Netlify site at api.marlasowards.com. This page covers only how this site connects to it.

Quick reference

  • src/pages/api-reference.js loads Scalar's script from jsDelivr, pinned to one version and checked with a subresource integrity hash, and points it at the spec on api.marlasowards.com. Scalar's proxy, telemetry, AI agent, and remote fonts are turned off (see Security).
  • Scalar's script loads only on this page. src/css/scalar-api-reference.css matches its look to the site's theme.
  • netlify.toml permanently redirects the API's old URLs on this domain to api.marlasowards.com.
  • To change the API, its data, or the reference page's text, work in the norway-data-api repo. The reference page picks up the change as soon as that site deploys, with no rebuild here.
  • For how the API got here, see How the API was built. For security, see Security.
  • The API repo's own docs are mirrored in this section: The Netlify Functions, The OpenAPI spec, The contract test, Maintaining the API, API security controls, and Design decisions. The API repo is the source of truth: when a doc there changes, update its mirror here.
  • The API's tutorial and how-to guides live in this repo, under /samples. For what they depend on and how to test them, see The tutorial and guides.

How it fits together​

Browser on www.marlasowards.com/api-reference        (this repo)
   │  loads Scalar      → cdn.jsdelivr.net (pinned version + integrity hash)
   │  loads the spec    → api.marlasowards.com/openapi/norway-data.yaml
   │  Test Request      → api.marlasowards.com/norway-data/v1/...
   ▼
api.marlasowards.com                                  (norway-data-api repo)
   ├── public/openapi/norway-data.yaml
   └── Netlify Functions: netlify/functions/

The page and the API are on different domains, so the browser makes cross-origin requests. The API allows any origin, for both the spec and the API responses, so no extra setup is needed. Because the spec URL is absolute, the page works the same under npm start, in deploy previews, and in production.

The page​

src/pages/api-reference.js is a regular Docusaurus page. When it mounts, it adds Scalar's script to the page once, then calls Scalar.createApiReference() with the spec URL (https://api.marlasowards.com/openapi/norway-data.yaml).

Scalar's URL and integrity hash live in src/data/scalar.mjs, because two files use them: the page loads that exact file, and the Content Security Policy allows only that file (and its source map), not the whole CDN.

src/data/scalar.mjs
export const SCALAR_SRC = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.73.1/dist/browser/standalone.js';
export const SCALAR_INTEGRITY = 'sha384-kYDGzV91Jnn3TbHINV3nt54riK2uMJDfN5Al8dAkz4FssELTBWbD8rgw32sTKfOi';
export const SCALAR_SOURCE_MAP = `${SCALAR_SRC}.map`;
  • The version is pinned in the URL, so a Scalar release can't change the page without a change in this repo.
  • The integrity hash makes the browser refuse the script if the CDN ever serves different bytes for that URL. The hash matches the file in Scalar's npm package. If the script fails to load, the page shows a message instead of an empty page.
  • hideDarkModeToggle: true hides Scalar's own toggle, so the page follows the site's light or dark mode.
  • proxyUrl: '', telemetry: false, agent: { disabled: true }, and withDefaultFonts: false stop Scalar from contacting its own servers. See Security.

Why not the @scalar/docusaurus plugin​

The site used the @scalar/docusaurus plugin at first. It was replaced because the plugin:

  • Adds Scalar's 4.5 MB script to every page of the site, not only /api-reference.
  • Has no way to set an integrity hash, so a compromised CDN could run code on every page.

The plugin's only other job was the theme stylesheet, which now lives in src/css/scalar-api-reference.css (MIT-licensed, with attribution in the file).

The navbar link is a regular item in themeConfig.navbar.items. See Navbar.

Redirects for the old URLs​

The API used to be served from this domain through proxy rules. It moved to api.marlasowards.com because proxied requests skipped the API's rate limit. The old URLs still work through permanent redirects:

netlify.toml
[[redirects]]
  from = "/api/norway-data/*"
  to = "https://api.marlasowards.com/norway-data/:splat"
  status = 301

[[redirects]]
  from = "/openapi/norway-data.yaml"
  to = "https://api.marlasowards.com/openapi/norway-data.yaml"
  status = 301

The API repo's hourly smoke test checks these redirects, so a change here that breaks them shows up there.

Upgrade Scalar​

  1. Pick the new version, and get the integrity hash of its file. From a shell with curl and openssl:

    V=1.73.1   # the new version
    curl -sL "https://cdn.jsdelivr.net/npm/@scalar/api-reference@$V/dist/browser/standalone.js" \
      | openssl dgst -sha384 -binary | openssl base64 -A

  2. In src/data/scalar.mjs, update the version in SCALAR_SRC and set SCALAR_INTEGRITY to sha384- followed by the hash. The Content Security Policy picks up the new URL on the next build.

  3. Run npm start and check the reference page: the sidebar sections, the Test Request button, and the code samples.

  4. Check that the security options in createApiReference() still exist in the new version (search its bundle for proxyUrl, telemetry, agent, and withDefaultFonts), and that Test Request calls go straight to api.marlasowards.com, not proxy.scalar.com, in the browser's network tab.

  5. If the theme looks off, compare src/css/scalar-api-reference.css with the dist/theme.css file in the matching @scalar/docusaurus release.

The spec's introduction mentions the Test Request label by name, so if a new version renames it, update the spec in the API repo.

Troubleshooting​

The reference page says the viewer failed to load​

The browser couldn't load Scalar's script, or refused it because it didn't match the integrity hash. Check the browser console. An integrity error after an upgrade means SCALAR_INTEGRITY doesn't match the file in SCALAR_SRC: recompute it with the command above.

The reference page loads but shows no API​

The page couldn't load the spec. Run curl -I https://api.marlasowards.com/openapi/norway-data.yaml. It should return 200 with Access-Control-Allow-Origin: *. If it doesn't, check the API site's latest deploy.

Test Request shows "Failed to fetch"​

The request didn't reach the API, or the response was missing its CORS headers. Run the API repo's smoke test against production:

npm run smoke -- https://api.marlasowards.com --redirects

For problems inside the API, see the troubleshooting section of the Maintaining the API.