API changes

Abuna keeps the API working for the code you write today. Some changes come at any time, because code written as this page describes keeps working through them. Every other change comes with 90 days' notice.

Changes without notice

These can happen at any time. Write your code so it keeps working when they do:

• A new field in a response, an object, or an event's data. Ignore fields you don't know.
• A new event type. Answer 2xx to a webhook whose type you don't handle, and skip it.
• A new endpoint, or a new optional parameter on an existing one.
• A new value in a field that lists its values, like a new kind of notice or a new error code. Handle a value you don't know as you handle the closest one you do, or log it.
• A new pair in the X-Abuna-Signature header. Read the pairs you know and ignore the rest.
• IDs and cursors of a new length or form. Treat them as opaque strings. See IDs.
• New wording in an error's error sentence. Branch on code, never on the sentence.

Changes with 90 days' notice

Any other change that could break working code gets at least 90 days' notice before it takes effect. That includes removing or renaming an endpoint, a field, or an event type, changing a field's type or meaning, making an optional parameter required, and changing how webhooks are signed.

During those 90 days, the old behavior keeps working. The Changelog entry says what changes, the date it takes effect, and what to change in your code.

How you hear about changes

Every change is listed on the Changelog with its date. A change with notice is listed on the day the 90 days start.