API Versioning (GA)

[github-product-roadmap]

Summary

As the home for all developers, GitHub needs to provide a reliable and trusted set of APIs. A versioned API is a must-have for any platform at scale – lacking versioning makes it difficult for us to deprecate endpoints and build an easy-to-use and powerful API. A versioned API empowers us to give our customers a clear API roadmap with a predictable cadence. In order to build a trusted, world-class API, we’re working towards introducing calendar-based versioning for our API with long-term support of two years for each version. This effort will improve integrators’ trust in and excitement about our platform by providing a stable, consistent, and well-documented API and a roadmap of all upcoming platform releases.

Intended Outcome

A versioned API with long-term support for each version will improve the stability, consistency, and ease-of-use of our API by allowing partners and integrators to plan against our API changes.

How will it work?

Once implemented, API releases will be named with the date on which they are released (for example, 2021-04-01). Users will pick what version they want in each request using a header - with headerless requests defaulted to the first version for a limited period. Each version will be supported for at least 2 years, meaning the contract would not change and the data types would not regress. All breaking changes to our API would necessitate a new version, and each version will have explicit long-term support.