Versioning and deprecation

What can change without notice, and how breaking changes are introduced.

The major version is in the path, /v1, and in the Eslana-Api-Version header of every response and webhook.

Changes we make without notice

• New endpoints, optional request fields, response fields and headers.
• New error codes, batch result fields and webhook event types.
• Clearer error messages. Act on code, never on the wording of error.

Write your integration to ignore fields and event types it does not recognise.

Breaking changes

Removing or renaming anything, changing a field’s meaning or type, or tightening validation ships as a new major version, /v2. /v1 keeps working for at least 12 months after /v2 is released.

A route on its way out answers with a Deprecation header (when it was deprecated), a Sunset header (when it stops working) and a Link to the changelog entry that explains the replacement. Companies whose keys still call it are contacted before the sunset date.

Every change is listed in the changelog.