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.

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

Operations in a stable API version should be considered stable and ready for production use unless they are explicitly marked as preview. Only non-breaking changes will be introduced to stable operations in 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.

Preview

A preview endpoint is available for early use, but it is not covered by the same stability guarantees as stable operations. Preview endpoints may change in backward-incompatible ways or be removed before they become stable.

We mark preview endpoints by suffixing the endpoint names (summary) [Preview]. For example Create a tag group [Preview].

Only rely on preview endpoints if you can accommodate changes before general availability. When a preview endpoint becomes stable, the [Preview] suffix and preview notice will be removed.

Backward and Non-Backward Compatible Changes

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

To ensure the security, performance, and reliability of our platform, we periodically retire older API versions. We follow a structured process to give you ample time to migrate your integrations.

Deprecation Phase

When a new API version is introduced with breaking changes, the older version is marked as Deprecated.

• Support: Deprecated versions receive critical security patches and high-priority bug fixes but no new features.
• Communication: We will announce deprecation dates via our developer mailing list and the Developer Portal.
• Headers: You can monitor the Bokio-Api-Deprecated-Versions header in every API response to see if your current integration is using an outdated version.

Brownout Periods

As a version nears its final Sunset Date, we implement scheduled Brownouts. A brownout is an intentional, temporary service interruption designed to help you identify any remaining legacy integrations in your environment that might have been overlooked.

• How it works: During a brownout, the API will intermittently return a 410 Gone status code (e.g., during every other hour).
• Purpose: These windows of unavailability ensure that your monitoring systems and logs catch the deprecated dependency before the version is permanently disabled.
• Response Format: Brownout responses follow our standard error format with the code version_sunset_brownout.

Sunsetting (Deactivation)

On the communicated Sunset Date, the version will be permanently deactivated. All requests to a sunsetted version will return a final error response, and the endpoint will no longer be accessible.

We strongly recommend migrating to the latest stable API version as soon as a deprecation notice is issued to ensure continuous service and access to the latest Bokio features.

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.