Definition
Have you ever noticed how newspapers and magazines are identified by their publication date? The March 15, 2024 edition of The New York Times is a specific, identifiable snapshot of news from that day. If someone asks “which newspaper do you have?”, the date tells them exactly what version of information they’re looking at. Date-based versioning applies this same intuitive concept to APIs - instead of using abstract version numbers like “v2.3.1”, your API version is simply the date it was released.
Date-based versioning (also called CalVer or calendar versioning) uses release dates as version identifiers. When you call an API with version “2024-04-15”, you know exactly when that version of the API was published. This approach has gained significant popularity because it provides immediate context - a version number like “v4” tells you nothing about how old it is or what era of the product it represents, but “2023-01-15” instantly tells you this version is from January 2023. Stripe, one of the world’s most respected payment APIs, pioneered this approach and it’s now used by major platforms including Twilio, GitHub, and Google Cloud.
The beauty of date-based versioning is that it creates a natural timeline of your API’s evolution. When you pin your application to version “2022-08-01”, you’re essentially saying “I want the API exactly as it existed on August 1, 2022.” This makes migration planning much easier - you can clearly see how many versions behind you are, and API providers typically communicate things like “all versions before 2023-01-01 will be deprecated.” It also makes debugging easier: if your code worked yesterday but broke today, you can see exactly which API version change might have caused it based on the timeline.
Example
Real-World Scenario 1: Stripe Payment Processing Stripe is the poster child for date-based versioning. When you integrate Stripe, every account is pinned to a specific API version like “2023-10-16” or “2024-04-10”. If you created your Stripe account in 2022, your default version might be “2022-11-15”. When Stripe adds new features or changes behavior, they release a new dated version. You can stay on your current version indefinitely, upgrade to the latest, or test against any version in between. The date tells you exactly how far behind (or current) you are.
Real-World Scenario 2: Twilio Communications API When building a messaging app with Twilio, you specify a version date like “2010-04-01” (Twilio’s original release) or “2020-05-01” (with modern features). If you’re maintaining an older app that works perfectly on version “2015-01-01”, you don’t need to touch it - that version continues working exactly as documented. New apps can use the latest version with all current capabilities. The dates make it crystal clear which documentation to reference.
Real-World Scenario 3: GitHub’s REST API
GitHub uses header-based date versioning: X-GitHub-Api-Version: 2022-11-28. If you’re building a CI/CD tool that integrates with GitHub, you pin to a specific date version. When GitHub introduces breaking changes (like modifying how pull request comments work), they release a new dated version. Your tool keeps working on the old version while you plan your upgrade on your own schedule.
Real-World Scenario 4: Google Cloud APIs Google Cloud APIs use dates like “2023-05-01” for their service versions. When you deploy a cloud function that calls Google’s Vision API, you specify which version you want. If Google improves their image recognition algorithms and changes the response format, that goes into a new dated version. Your existing code continues to get the exact behavior it was built for.
Analogy
The Newspaper Edition Analogy: Newspapers have been using date-based “versioning” for over a century. The March 15, 2024 edition is different from March 16, 2024. If you’re researching what happened on a specific day, you know exactly which edition to find. The date IS the version. APIs work the same way - the date tells you exactly which “edition” of the API you’re using.
The Software Snapshot Analogy: Think of date-based versions like snapshots in a time-travel movie. Version “2023-06-01” is the API frozen in time as it existed on June 1, 2023. Calling that version is like visiting that exact moment in history - everything behaves exactly as it did then, regardless of what changes have happened since.
The Wine Vintage Analogy: Wine is identified by its vintage year - a 2019 Bordeaux is distinctly different from a 2020 Bordeaux. The year tells you about the weather conditions, grape quality, and characteristics you can expect. Similarly, an API version “2024-01-01” tells you about the capabilities, behaviors, and features from that period of the API’s evolution.
The Tax Form Year Analogy: When you file taxes, you use forms specific to the tax year - the 2023 form has different rules than the 2022 form. You would never accidentally use the wrong year’s form because the year is prominent. Date-based API versions work the same way - you always know exactly which “rules” you’re working with because the date is right there.
Code Example
// Date-based versioning (Stripe style)
GET https://api.company.com/payments
Stripe-Version: 2024-04-10
// Or in URL path
GET https://api.company.com/2024-04-10/payments
// Version negotiation with dates
GET https://api.company.com/payments
X-API-Version: 2024-04-10
Accept: application/json
// Response with version info
[HTTP/1.1](https://reference.apios.info/terms/http-1-1/) 200 OK
X-API-Version: 2024-04-10
X-API-Version-Previous: 2023-10-16
X-API-Version-Latest: 2024-11-01
// Version changelog endpoint
GET https://api.company.com/versions
{
"versions": [
{
"date": "2024-04-10",
"changes": ["Added 3DS2 authentication", "Deprecated card tokens"],
"breaking": true
},
{
"date": "2023-10-16",
"changes": ["Added Apple Pay support", "Enhanced fraud detection"],
"breaking": false
}
],
"currentVersion": "2024-04-10",
"minimumSupported": "2023-01-01"
}