Date-based versioning
Easily understand when a version was released.
Versioning an API using a date format, such as YYYY-MM-DD, is a simple and intuitive way to distinguish between different releases. Each release was released on the date that is the release's version.
Date-based versioning is incremental and progressive. Each new version supersedes the last. This may make it more difficult to deliver a long-term support (LTS) model for enterprise customers.
Because a release's version lacks semantic meaning, developers cannot understand whether a change is breaking or not just by looking at its date.
Pros
- Developers can easily understand the chronological order of versions based on the dates.
- Well suited to frequently-updated APIs.
- Changelogs are simple to maintain as each release can be appended to the changelog.
Cons
- Lack of semantic meaning.
- Breaking changes are more difficult to communicate.
- Long-term support may be more difficult to provide.
- Unable to distinguish between multiple releases that occur on the same day.
- Ill suited to being specified as a URL prefix.
Usage
You can allow by the developer to set the version on a specific request by accepting a header, such as ExampleCo-Version.
Date version specified as a header
curl https://api.example.com/items \ -H "ExampleCo-Version: 2023-01-22"
Should I use it?
Does your API changes frequently, a date format can be more manageable.
Implementation notes
Date-based versioning formats should adopt the ISO 8601 standard, which provides an internationally-recognized format for describing calendar dates.
OpenAPI reference
{ "openapi": "3.1.0", "info": { "title": "Date-Based Versioning API", "version": "2022-10-27" } }