I’ve recently taken a closer look at the #Foursquare #API (updating the long unmaintained Platypush plugin, details on why coming soon).
At first their new API versioning schema seemed a bit confusing (why would anyone use arbitrary YYYYMMDD strings as versions?), but a closer look at how they implemented it revealed a quite clever design decision:
Versioning is controlled by the v parameter, which is a date that represents the “version” of the API for which you expect from Foursquare. It is designed to give developers the freedom to adapt to Foursquare API changes on their own schedule. The value of the v parameter is a date in YYYYMMDD format that lets you tell us “I’m prepared for API changes up to this date.”
You know when you look at an engineering decision that is so elegant and obvious that you think “damn, how could nobody think of this before?”
Nearly two decades spent managing /v1, /v2, /v2.5, /v2.almost3, /v3, managing migrations and deprecations, documenting breaking changes, introducing exponentially thicker layers of schemas and converters, and the obvious solution was just there under our nose.
Why don’t you just start with defining the base schemas of your API objects at the time of their first release, and then every time you add, modify or delete a field, or change some return type, or add a value to an enum, you just version the change with a timestamp?
Let the developer say “I understand the language that your API spoke 3 months ago”, and you just dynamically create the schemas, GraphQL or ORM snippets to parse requests and responses as of that date.
No more breaking changes. No more forced migrations. No more boilerplate to explicitly convert payloads across different API versions.
You construct the response by first applying the base schema, and then gradually patching it - just like you would do with a git rebase, or an ORM migration tool.
A downside may probably be that you can never really delete a column from the db if it was ever used by any version of your API.
And a challenge may also be to adapt tools like #OpenAPI / #Swagger that were designed around static schemas to also work with “dynamically versioned” selections.
But to me the problems it solves far outweight the downsides.
https://docs.foursquare.com/developer/reference/versioning
Join me at DevFest Pisa 2025 where I’ll be sharing insights on how to elevate API experiences! 
When: April 12, 2025
Time: 11:40 AM
Where: MACC - Pisa - Italy
Schedule: https://devfest.gdgpisa.it/talk/overlay-and-arazzo-from-api-definitions-to-api-experiences/
Qiita - 人気の記事 
Today, we’re continuing our side quest: building a type validation system from OpenAPI specs. Yesterday was just the beginning—let’s refine, expand, and make it truly useful. If you're into API design and type safety, come hang out!