Versioning

This page states how API v1 changes, so you know what can break and what cannot. The current version is 1.9.1; the served OpenAPI document carries it in info.version.

The v1 policy

• Additive only. A new version adds endpoints, optional request fields and parameters, response fields and enum values. No path, field or enum value is removed or renamed, no type changes, and no optional input becomes required.
• New fields appear. Ignore fields you do not know, and in unions (page.kind, block type) handle the values you know and skip the rest.
• Behaviour changes are labelled. Now and then a change tightens what the API accepts or changes a value under the same field, for example refusing SVG uploads (1.6.1) or putting a visit's own price before the treatment's (1.8.1). Each such change is marked behaviour change in the changelog, never hidden among the additions.
• Anything that cannot be additive goes to /api/v2, next to v1, not instead of it.

Version numbers

info.version follows semantic versioning within v1: a minor version (1.9.0) adds something, a patch version (1.9.1) fixes something or changes only the documentation. Every change to the document bumps it, in the same release as the change.

Since badges

Reference pages mark every operation, and every field newer than its operation, with the first version of the spec that documents it (x-pp-since in the OpenAPI document). Production always runs the current version, so the badge tells you what an older SDK, or a client generated from an older document, does not know yet.

Error messages

The error text of a response is for people and is written in Polish; it may change between versions. Branch on the HTTP status and, where the endpoint sends one, on code. See Errors.

The SDK

@pozyskajpacjenta/sdk has its own version (0.8.1 today) and its changelog says which API version each release follows. An SDK update never changes the API: an older SDK keeps working against a newer v1.