Versioning & deprecation

The API's version is in its address: https://picked.nl/api/v1. Within v1, Picked only adds. What your integration relies on today keeps working.

What stays the same in v1

Within v1, Picked doesn't remove or rename an endpoint, a field or an error code, doesn't change a field's type or meaning, and doesn't make an optional field required. Each change is checked against the published specification of v1 before it ships.

What can be added

These changes can happen in v1 at any time, without notice:

• a new endpoint;
• a new optional field or query parameter in a request;
• a new field in a response;
• a new error code;
• a new response header.

So build your integration to cope with them:

• Ignore fields you don't know. Don't fail on an unexpected key in a response, and don't validate responses against a closed schema.
• Fall back on the HTTP status when you meet an error code you don't know. See Errors.
• Don't depend on the order of the keys in a response.

Deprecation

When something in v1 has to be removed or changed incompatibly, Picked announces it at least 12 months before it happens, on the changelog. The old behaviour keeps working throughout those 12 months, so you have time to move over.

The specification

The full v1 specification is published as OpenAPI at /docs/api.json and readable at /docs/api. You can generate a client from it, or compare it between releases to see exactly what changed.