eschutho opened a new issue, #34506: URL: https://github.com/apache/superset/issues/34506
## Motivation The motivation behind this proposal is to provide a more stable, reliable, and consistent API for all our users and partners. We recognize that our API is a critical interface for third-party systems and integrations. By ensuring its stability, we aim to foster a more seamless and efficient development process for everyone who interacts with Superset. This is not just about making our API easier to use, but also about ensuring that it can effectively support the diverse and evolving needs of our users and partners. We understand the importance of a stable API in ensuring the smooth operation of third-party systems and aim to deliver a user-friendly experience that prioritizes reliability and consistency. ## Proposed Change We propose a sequential pattern for API semantic versioning. This would involve a simple, straightforward progression: v1, v2, v3, and so forth. The primary principle behind this approach is the avoidance of backward breaking changes. We are firmly committed to ensuring that any changes we make to the API will not disrupt the functionality of existing integrations. We believe that this principle will provide a stable foundation for developers and partners to build upon, reducing the likelihood of unexpected surprises or complications that might arise from sudden changes in the API. Under our current API semantic versioning policy, each API endpoint clearly shows the version number in its URL. For instance, an endpoint for retrieving data looks like this: `/api/v1/data`. In this URL, `v1` indicates that this is version 1 of the API. This clear and transparent approach ensures that developers can quickly identify the API version they are working with, promoting efficient and error-free development. Under our new policy, we are committed to ensuring stability and backward compatibility. As such, **we will not push any breaking changes to an existing API.** Any breaking changes should only be introduced in a new version of the API. This policy allows for easier management of changes and enhances the reliability of our API for all users. **Additionally, single endpoint deprecations will not be removed during open source Superset major versions**. The `@deprecations` decorator **should now refer to API versions**, not application versions, and we no longer will mark a specific endpoint as deprecated, but rather the entire version. This will ensure a clear and consistent understanding of the deprecation status across different versions of the API. When we roll out the new api version, **every endpoint on the old version will have the `@deprecation` flag**. **A new API version can be introduced during any release. However, the removal of old API versions will only occur with a major Superset release.** This strategy ensures that users and partners have ample warning and opportunity to update their systems to a newer API version, minimizing disruptions to their operations. As part of our commitment to maintaining a stable and reliable API, we will support **up to two API versions at a time**. This means that when a new version is released, we will **continue to support the previous version** to ensure a seamless transition for our users and partners. This approach will allow users and partners sufficient time to adapt to the new version without experiencing any disruption in their ongoing operations. It's also crucial to note that our API is designed to function independently of the application. This means developers and partners should be able to use the API without necessarily having to delve into the specifics of the Superset application. This independence fosters greater flexibility, allowing third-party systems to interact with our API effectively and efficiently, irrespective of changes or updates within the Superset application itself. Our goal is to maintain a robust and stable API that can serve as a reliable interface for a wide range of third-party systems. ## **Rolling out a new API version** While we are building the new api, we can mark the new version as `beta` possibly through a decorator that logs a message that the api version is in beta. We will then copy over or rewrite the existing apis to the new version endpoint and then point all the existing Superset api versions to the new one. It will help to have a config in the application that points all the client side endpoints to one version, to make this transition easier. ## Maintaining two APIs Maintaining two versions of an API at the same time may seem like an extra overhead. However, it is a necessary step to ensure a smooth transition for our users and partners. When a new version is released, the old version would still be available, giving users and partners ample time to adapt their systems to the new version. This approach provides stability and avoids disruption to ongoing operations. Although we will support two API versions at a time to provide a smooth transition, it's crucial to note that **we will not keep both versions around for longer than absolutely necessary**. Once users and partners have had sufficient time to transition to the new version, the older version will be removed. This is to ensure that our resources are focused on maintaining and improving the most current and efficient version of our API. In the context of the Superset application, it **should only be run on one API version at a time**. Users should be encouraged to use all endpoints from a single API version rather than mixing endpoints from different versions. This approach is intended to ensure consistency and reduce the potential for errors or unexpected behaviors. It's crucial to maintain a high level of transparency and communication during this period. Therefore, we'll provide clear documentation and support to help users understand the differences between the two versions and guide them through the transition process. Regular updates on the status of the old API, including the planned date for its deprecation, will be communicated to all users. ## New or Changed Public Interfaces We could introduce an optional configuration that allows passing an End-of-Life (EOL) date with API deprecation notices. This provides a clear timeline for when deprecated API versions will cease to be supported, facilitating the transition process for developers. By providing this information upfront, developers can plan their migration to newer API versions more effectively and avoid potential disruptions. ## New dependencies We may need to adjust configurations in Flask App Builder (FAB) to support more than one API version at a time. ## Migration Plan and Compatibility To implement this change, we will have to revise the existing deprecation flags so that they reference API versions instead of application versions. ## Rejected Alternatives While we did consider various alternatives, including aligning the API versioning system with the application's, we found this approach to be problematic. For instance, maintaining an old version concurrently with a new one would require inventive naming of the API endpoints, which could potentially deviate from standard RESTful nomenclature. Moreover, in situations where users have a service calling an API, synchronizing a version bump for both the Superset application and the service calling the API could be challenging. For example, if we needed to change the `/chart` GET endpoint in a breaking way, we would need to rename the resource in order to create a new alternative endpoint while marking the old one as deprecated. In our exploration of options, we also noted that some API versions utilize minor versions. However, we did not see any substantial benefits that would justify the added complexity. Hence, we decided on our current strategy. It aligns with common industry practices for API versioning, aiming to keep our API as stable and reliable as possible, while remaining flexible enough to accommodate future changes and improvements. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
