Public API: calls from another website
A municipality can put a search box on its own website that queries its publications straight from the reader's browser. The browser only allows such a call when OpenCatalogi names that website in its CORS headers. Which websites it names is a list the administrator keeps.
Set the allowed websites
Open Administration settings → OpenCatalogi → Publishing options and fill in Websites that may call the public API, one website per line:
https://www.voorbeeldgemeente.nl
https://zoeken.voorbeeldgemeente.nl:8443
- A line is a bare origin:
https://orhttp://, the host and an optional port. A path, query or trailing slash is refused, and the message names the line (https://www.voorbeeldgemeente.nl/zoekenis refused;https://www.voorbeeldgemeente.nlis right). *allows every website. It is the default, and a list that holds*allows every website too.- Upper case is stored in lower case, because a browser sends its origin in lower case.
The same list is the app config key cors_allowed_origins, comma separated:
occ config:app:set opencatalogi cors_allowed_origins --value="https://www.voorbeeldgemeente.nl,https://zoeken.voorbeeldgemeente.nl:8443"
What the answers say
A website on the list is named back in Access-Control-Allow-Origin. A website that is not on the list is never named: the answer names the first website on the list, so the browser blocks the call. Credentials are never allowed (Access-Control-Allow-Credentials: false), so a cross-origin call is always an anonymous one.
These endpoints answer a preflight (OPTIONS) and carry the headers on every answer, errors included:
GET /api/searchand/api/search/{id},/attachments,/download,/uses,/usedGET /api/federation/publicationsand/api/federation/publications/{id},/attachments,/download,/uses,/used- the publication list
GET /api/{catalogSlug}and the other public endpoints, which already did
The search and federation answers carry Vary: Origin, so a CDN keeps one site's answer apart from another's (see cache headers).
Search from another website
const base = 'https://cloud.voorbeeldgemeente.nl/index.php/apps/opencatalogi/api'
const answer = await fetch(`${base}/search?_search=${encodeURIComponent('begroting')}`)
const { results, total } = await answer.json()
The call carries no cookies and sees what an anonymous visitor sees.