|
Listen to this story
|
GitHub has introduced a calendar-based versioning to Rest API, providing smooth migration for integrators to new versions of the API.
The last time GitHub made any changes to its API was over a decade ago when it launched version 3 (“V3”). Since then, the company hasn’t been able to bring occasional breaking changes and ensure that all integrations have smooth migration paths or time to upgrade their integrations to new versions of the API, mainly because it didn’t have the right tools and processes to enable it.
Updates are necessary to APIs as they bring new features, fix bugs, and enhance the developer experience.
How it works
The company will release new versions every time it has to make breaking changes to the Rest API. By referring to this document, developers can see what counts as breaking and non-breaking.
Every new version will be named after the date it was released. After the release, the previous versions of the Rest API will still be available for up to two years. Users can choose the version they want after a new release on a request-by-request basis using the X-GitHub-Api-Version header.
However, the versioning model only applies to breaking changes; non-breaking changes are available across all APIs.
How to apply
The Rest API currently in use is deemed version 2022-11-28. GitHub recommends that its integrators update their integration to send the new X-GitHub-Api-Version: 2022-11-28 header. However, this doesn’t mean developers must change the integration itself.
This will allow users to upgrade to future versions of the API by pointing the X-GitHub-Api-Version header to the new version and ensuring that the integration is compatible with the version’s modifications.
For more information, read here.
