API Versioning

Bokio is committed to providing a reliable and stable API for developers to build integrations on top of. For us, it's a priority to stay on a path of non-breaking changes for as long as possible. However, sometimes APIs need to introduce breaking changes to provide important improvements.

📘

Version overview

Version	Release date	Deprecation date	Sunset date
Beta	2024-11-19	2025-08-19	2025-10-01
v1 (latest version)	2025-08-19

Versioning Scheme

Bokio API versions are indicated within the URL path. For example, requests to https://api.bokio.se/v1/invoices will access version 1 of the API. When a new version is released with breaking changes, it will receive a new version number (e.g., v2).

Our version numbers in the URL correspond to the MAJOR version of a semantic versioning scheme. Non-breaking changes (like adding new fields or operations) will not cause a change to the URL version number.

Stable Version

All operations in our API should be considered stable and ready for production use. Only non-breaking changes will be introduced to a current stable version. If we need to introduce breaking changes, they will be released in a new version that you can upgrade to.

From the date of a deprecation announcement for a specific version, there will be an extended amount of time for you to upgrade your integration. This timeframe will be clearly communicated and will initially be 3 months. As the API matures the intention is to increase the deprecation period.

Backward and Non-Backward Compatible Changes

❗️

Note that security concerns could take priority over backward compatibility when it comes to changing authentication or authorization requirements.

To ensure your integration remains stable, it's important to understand the difference between breaking and non-breaking changes.

API Versioning Headers

To help you manage your integration, every response from the Bokio API will include the following HTTP headers:

• Bokio-Api-Supported-Versions: This header will list all the API versions that are currently active and fully supported.
• Bokio-Api-Deprecated-Versions: This header will list any versions that are deprecated. This is your signal to begin planning a migration to a supported version.

You can use these headers to programmatically check the status of the API versions without needing to consult the documentation.

Version Deprecation and Sunsetting

When a new API version is introduced with breaking changes, older versions will be deprecated. We will communicate deprecation notices and sunsetting schedules via our developer mailing list and through announcements in the developer portal, allowing ample time for you to migrate your integrations. You can also monitor the Bokio-Api-Deprecated-Versions header in our API responses for real-time information. Only the latest stable API version will receive new feature updates and enhancements, though bug fixes may be applied to supported older versions.

Best Practices for Future-Proofing Your Integration

To ensure your integration is resilient and can adapt to future changes, we recommend the following practices:

• Tolerate New Fields: Your code should be prepared to handle and ignore new fields that may be added to API responses. Do not fail if an unexpected field is present.
• Handle New Enum Values: Do not hard-code a fixed list of enum values. Your code should be able to gracefully handle new, unexpected enum values in the future.
• Use the API Specification: When upgrading to a new major version, use the dedicated OpenAPI specification file to generate a new API client. This ensures your code is built against the correct, up-to-date models.
• Design for Version-Awareness: Treat the API version (v1, v2, etc.) as a configurable setting in your application. This simplifies the process of switching to a new version when it becomes available.
• Monitor API Headers and Plan Ahead: Regularly check the Bokio-Api-Supported-Versions and Bokio-Api-Deprecated-Versions headers. When you see your version listed as deprecated, begin the process of planning your migration to a supported version to avoid service disruption.