Spec contract

The Happklaar public API is described by a single OpenAPI 3.1 document served live at https://api.happklaar.nl/docs.json. This docs site (docs.happklaar.nl) and any third-party tooling — SDK generators, Postman, Insomnia, internal API explorers — MAY depend on that URL as a stable contract for discovering operations, schemas, and authentication requirements.

This page describes the contract: what URL serves the spec, how versioning is signalled, how often the spec changes, and what guarantees you can rely on when integrating against it. It does not embed or proxy the spec itself — that document lives at the canonical URL and is the single source of truth.

Canonical URL

The canonical spec URL is:

https://api.happklaar.nl/docs.json

It returns OpenAPI 3.1 JSON. The endpoint is unauthenticated, idempotent, and safe to fetch at build time from SDK codegen tools, schema validators, or external API explorers.

The path /docs.json is permanent. If we ever need to retire it, we will publish a 90-day advance notice on Changelog before the URL is removed.

The document reflects exactly what production serves — there is no separate "documentation spec" that drifts from the runtime contract. A build-time drift check keeps the spec in lock-step with the deployed API.

Versioning policy

All API routes live under the /v1 prefix on api.happklaar.nl. Breaking changes do not mutate /v1 in place — they ship a new /v2 surface, and the existing /v1 surface continues to operate for a 6-month deprecation window before removal.

See Versioning for the full deprecation policy.

Today only /v1 exists; no /v2 is in flight. When that changes, both surfaces will be present in the same /docs.json document and clients can pick the version they target via the servers block or path prefix.

Change cadence

Spec changes are tracked release-by-release. Every commit that bumps the upstream spec.lock.json produces a generated changelog entry via oasdiff, recording added operations, breaking changes, and modified schemas. Entries land on the Changelog page in reverse chronological order.

If you maintain an SDK or integration that depends on the spec, subscribe to the Changelog or watch the spec bump commits in the upstream repository — both surface the same diff content.

Stability guarantees for third-party consumers

Guarantee	Scope	Notes
URL stability	The path `/docs.json` on `api.happklaar.nl` is permanent.	URL retirement requires a 90-day advance notice via Changelog.
Content stability	The spec is OpenAPI 3.1. Breaking changes to the schema (new required fields, type narrowing, enum removal, route removal) ship under a new `/v2/...` surface; `/v1/...` continues to operate during the 6-month deprecation window.	See Versioning for deprecation timing.
Authentication	Spec discovery (the GET to `/docs.json`) is unauthenticated. Calling the documented endpoints requires a Personal Access Token.	See Authentication for the full PAT flow and bearer-only posture.
Cross-origin	CORS allows `https://docs.happklaar.nl`. For third-party consumers, `/docs.json` returns `Access-Control-Allow-Origin: *` so static SDK generators and external docs viewers can fetch it from any origin.	Calls to documented `/v1/...` endpoints follow the API's own CORS allowlist, which is narrower than the spec's.

Where this contract is consumed

docs.happklaar.nl itself (this site) reads the spec at build time and renders per-module catalog views from it. The rendered docs you are reading right now are derived from the same canonical URL.
Third-party consumers (OpenAPI-driven SDK codegen tools, Postman, Insomnia, custom integrations) can fetch the URL directly. Treat the spec as authoritative for operation shapes, request/response schemas, error envelopes, and authentication requirements — this docs site is downstream of the same source.

Canonical URL

The canonical spec URL is:

It returns OpenAPI 3.1 JSON. The endpoint is unauthenticated, idempotent, and safe to fetch at build time from SDK codegen tools, schema validators, or external API explorers.

The path /docs.json is permanent. If we ever need to retire it, we will publish a 90-day advance notice on Changelog before the URL is removed.

Versioning policy

See Versioning for the full deprecation policy.

Change cadence

If you maintain an SDK or integration that depends on the spec, subscribe to the Changelog or watch the spec bump commits in the upstream repository — both surface the same diff content.

Stability guarantees for third-party consumers

Guarantee

Scope

Notes

URL stability

The path /docs.json on api.happklaar.nl is permanent.

URL retirement requires a 90-day advance notice via Changelog.

Content stability

The spec is OpenAPI 3.1. Breaking changes to the schema (new required fields, type narrowing, enum removal, route removal) ship under a new /v2/... surface; /v1/... continues to operate during the 6-month deprecation window.

See Versioning for deprecation timing.

Authentication

Spec discovery (the GET to /docs.json) is unauthenticated. Calling the documented endpoints requires a Personal Access Token.

See Authentication for the full PAT flow and bearer-only posture.

Cross-origin

CORS allows https://docs.happklaar.nl. For third-party consumers, /docs.json returns Access-Control-Allow-Origin: * so static SDK generators and external docs viewers can fetch it from any origin.

Calls to documented /v1/... endpoints follow the API's own CORS allowlist, which is narrower than the spec's.

Where this contract is consumed

docs.happklaar.nl itself (this site) reads the spec at build time and renders per-module catalog views from it. The rendered docs you are reading right now are derived from the same canonical URL.

Third-party consumers (OpenAPI-driven SDK codegen tools, Postman, Insomnia, custom integrations) can fetch the URL directly. Treat the spec as authoritative for operation shapes, request/response schemas, error envelopes, and authentication requirements — this docs site is downstream of the same source.