niiko/developers

The contract

Versioning

Every action and every read carries its version in the contract, the scope and the URL. A new version is a new scope: credentials issued for @1 keep working exactly as the day they were issued.

Last updated

Where the version lives

In the scope (crm.call_logged@1), in the SDK method's docstring, and optionally in the URL query (?version=1). Adopting @2 is a decision you make by issuing a new key or authorizing the app again — never something an install does for you.

How a version retires

A version is announced as deprecated with two dates — since when, and after when it stops — and the window is never shorter than 30 days. While it lasts, every response from that version carries a Sunset header. After it, the version answers 410 version_retired with the dates inside: not a 404, because a 404 says «does not exist» and sends you looking for a typo; a 410 says «existed, no longer does» and sends you to read the notice.

Retired and deprecated versions

None yet. Every action and read is at its first version.

Package versions

The clients follow semantic versioning and are regenerated when the contract changes. Every published version has its own page with the date it reached the registry.