Deprecation and backward compatibility
Explains how deprecation and backward compatibility works
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. Sometimes though, APIs need to introduce breaking changes to be able to provide improvements.
Beta and stable version
With the Bokio API currently forming the need for quickly adapting to feedback is our number of priority. Our backward compatibility commitment is distinguished between what state the API is in.
While backward compatibility is critical in providing a stable API, it limits how quickly the API can improve. To be stable and also to be able to quickly iterate based on feedback, we define two versions for the API: Beta version and stable version.
- Beta version, contains all the new things in the API but without backward compatibility.
- Stable version, contain stable functionality with backward compatibility and a notice period.
Beta version
In Beta version, operations are not yet officially released. These operations are still in development and may undergo breaking changes before they are fully supported. Note that ee will aim at avoiding breaking changes.
Since there is no backward compatibility, please be prepared to make updates as needed. Note that operations may not move from beta to release at the same time.
Stable version
For stable versions, operations should be considered stable and ready for production use. Only non-breaking changes will be introduced for a stable version. If there are breaking changes they will be introduced in a new version that you can upgrade to.
From the date of deprecation announcement there will be an extended amount of time for you to upgrade your integration, likely 3–12 months. We will be more specific on the timespan for upgrade when we introduce our first stable version.
Please note that it is recommended to use the stable operations for production applications to ensure stability and compatibility.
Breaking and non-breaking changes
The breaking and non-breaking changes are defined by the table below.
Note that secuity concerns could take priority over backward compatibility when it comes to changing authentication or authorization requirements.
| Type of change | Change impact |
|---|---|
| Adding operation | ✅ Non-breaking |
| Adding optional request field | ✅ Non-breaking |
| Adding optional request header | ✅ Non-breaking |
| Adding optional query parameter | ✅ Non-breaking |
| Adding response field | ✅ Non-breaking |
| Adding response header | ✅ Non-breaking |
| Adding enum values | ✅ Non-breaking |
| Removing operation | ❌ Breaking |
| Adding required request field | ❌ Breaking |
| Adding required query parameter | ❌ Breaking |
| Adding validation rule to operation | ❌ Breaking |
| Removing or renaming response field | ❌ Breaking |
| Removing enum values | ❌ Breaking |
| Changing authentication requirements | ❌ Breaking |
| Changing authorization requirements | ❌ Breaking |
Updated 7 days ago