API stability and versioning
How the records API is versioned, what can change without notice, what does not change within v1, how the SDKs and the checker are versioned, and how a change is announced.
The records API is versioned in the URL path: its routes live under /api/v1/. An integration built against v1 keeps working without a code change. The Dashboard API's routes, under /dashboard, carry no version in the path.
What ships without notice
Additive changes ship continuously:
- New routes and new optional request fields.
- New fields in answers and in webhook payloads.
- New webhook event types. A handler ignores an event type it does not recognize.
- New values in fields documented as open lists.
Write a client that tolerates an unknown field and an unknown event type, and none of these changes will break it.
What does not change within v1
- A documented route, request field, or answer field is not removed or renamed.
- The type and meaning of an existing field do not change.
- Authentication, the webhook signature scheme, and what the check confirms do not change.
- An existing webhook event is not repurposed.
A change to any of these gets a new version path, and v1 keeps working beside it.
The SDKs and the checker
@pacspace-io/sdk, pacspace-sdk, and @pacspace-io/check carry their own version numbers, separate from the API's path. While a package is below 1.0, a release can change how a call is made; the changelog says when, and what to change. In 0.11.0 of the TypeScript SDK, for example, entry began counting from 1.
Deprecations
If a route or a field is ever deprecated, it is marked on its page and announced in the changelog well before any behavior changes, with a documented path across. A deprecated surface is still a working surface: within v1 it keeps answering.
The record outlives the interface
Versioning never touches what was committed. An entry committed under any version of the API reads back, and checks, under every later version, and the open-source checker reads the history files of earlier versions. A history file an evaluator kept checks the same way after every later release.