Versioning

Reference draft

This page comes from our reference drafts and is still being reviewed. Behaviour described here is the current build; defaults can change before launch.

The version is in the path: /v1/decide (https://api.ordainer.dev/v1/decide). Today there is one version, /v1.

What can change within /v1

We only add things:

• new fields in responses (for example, message was added to test_limit_reached answers);
• new reason values on a deny;
• new error codes;
• new optional request fields and new endpoints.

We don’t remove or rename fields, change a field’s type or meaning, or make an optional request field required.

Error codes

From launch on, error codes are frozen: new codes may be added, but existing codes are never renamed or removed. Before launch we may still rename a code; for example, idempotency_key_reused became idempotency_conflict (which also covers a retry with a different mode), and bad idempotency keys moved from invalid_request to their own invalid_idempotency_key. If you integrated before launch, check Errors for the current names.

What your client must do

• Ignore fields you don’t know. Don’t fail on an unexpected key. Most JSON libraries already do this; turn off any “strict” or “fail on unknown properties” option.
• Handle values you don’t know. Treat an unknown reason on a deny as a deny. Treat an unknown error.code by its HTTP status (4xx: fix the request or the account; 429: wait Retry-After; 5xx: retry with the same idempotency key).
• Branch on codes, not messages. message wording can change at any time.

Breaking changes

Breaking changes go to a new version (/v2). /v1 keeps working.

When an old version is scheduled to be turned off:

• you get at least 6 months’ notice;
• its responses carry a Deprecation header for that period, so you can find calls to it in your logs.

SDK versions

The Node SDK is on npm as ordainer (version 1.2.4; npm install ordainer). Its version is separate from the API version: SDK versions can have breaking changes even when the API doesn’t, and each package ships a CHANGELOG.md listing them.