4 ms·

My impression is that semver makes far more sense for published libraries (DLLs or ruby gems or npm packages etc) while date-based makes far more sense for SaaS

My impression is that semver makes far more sense for published libraries (DLLs or ruby gems or npm packages etc) while date-based makes far more sense for SaaS APIs. The constraints and usage patterns are fairly different between the two.

keithwhor 7y ago
What specifically about SaaS API constraints do you think makes a date-based approach more appealing than semver? My high-level feeling is that it’s just way more difficult to ship a SaaS API than a Ruby Gem, so adding semver to that is just another layer of API management everybody has to agree on. Do you agree with this assessment?
- eapache 7y ago
  For most published libraries every old version is always available and upgrading is never mandatory. For SaaS APIs the constraints of the business means that very few businesses (Stripe being the notable exception) want to support more than a handful of versions at a time, which results in versions regularly reaching end-of-life and completely disappearing. In this world, upgrading to newer APIs is mandatory and fairly frequent. The result is that API version handles need to prioritize different information. Libraries need a format that makes it easy to ballpark the size of changes between arbitrary not-strictly-sequential versions. SaaS APIs need a form that makes it easy to infer support windows and end-of-life status.
  - keithwhor 7y ago
    Good points. Do you think a combination of the two is possible, and how do you think that might work? year.month.minor.patch?
  - ahnick 7y ago
    > "SaaS APIs need a form that makes it easy to infer support windows and end-of-life status." You can infer that from the Release Date though. (e.g. Version 3.4.2 Released on 2019-12-17) To me the power of Semver is that it conveys complex relations between version iterations. For example: - 3.4.1 -> 3.4.2 is just fixing bugs in existing functionality - 3.4.2 -> 3.5.0 is an upgrade containing non-breaking changes - 3.5.0 -> 4.0.0 is an upgrade containing breaking changes As a developer, Semver + release date seems to convey everything date based versioning does plus I get the advantage of understanding at glance the importance and risk profile of each release. Note, this system does not reduce my obligation to run my own tests to verify that the version has in fact lived up to its intention (i.e. a minor version bump did not introduce a breaking change). Even though my obligation is not reduced, it does act as a filter to help prioritize development time for evaluation of performing upgrades.
kenrose 7y ago
One challenge with date based is that it can make your API seem old if it’s really stable. For example, see PagerDuty’s v1 events API: https://events.pagerduty.com/generic/2010-04-15/create_event.json https://events.pagerduty.com/generic/2010-04-15/create_event... Customers there would sometimes ask if that API was still relevant given its date is 9+ years old. In Shopify’s case, where there are quarterly version bumps and deprecation over time, date based makes better sense.

keithwhor 7y ago

What specifically about SaaS API constraints do you think makes a date-based approach more appealing than semver? My high-level feeling is that it’s just way more difficult to ship a SaaS API than a Ruby Gem, so adding semver to that is just another layer of API management everybody has to agree on. Do you agree with this assessment?

eapache 7y ago
For most published libraries every old version is always available and upgrading is never mandatory. For SaaS APIs the constraints of the business means that very few businesses (Stripe being the notable exception) want to support more than a handful of versions at a time, which results in versions regularly reaching end-of-life and completely disappearing. In this world, upgrading to newer APIs is mandatory and fairly frequent. The result is that API version handles need to prioritize different information. Libraries need a format that makes it easy to ballpark the size of changes between arbitrary not-strictly-sequential versions. SaaS APIs need a form that makes it easy to infer support windows and end-of-life status.
- keithwhor 7y ago
  Good points. Do you think a combination of the two is possible, and how do you think that might work? year.month.minor.patch?
- ahnick 7y ago
  > "SaaS APIs need a form that makes it easy to infer support windows and end-of-life status." You can infer that from the Release Date though. (e.g. Version 3.4.2 Released on 2019-12-17) To me the power of Semver is that it conveys complex relations between version iterations. For example: - 3.4.1 -> 3.4.2 is just fixing bugs in existing functionality - 3.4.2 -> 3.5.0 is an upgrade containing non-breaking changes - 3.5.0 -> 4.0.0 is an upgrade containing breaking changes As a developer, Semver + release date seems to convey everything date based versioning does plus I get the advantage of understanding at glance the importance and risk profile of each release. Note, this system does not reduce my obligation to run my own tests to verify that the version has in fact lived up to its intention (i.e. a minor version bump did not introduce a breaking change). Even though my obligation is not reduced, it does act as a filter to help prioritize development time for evaluation of performing upgrades.

kenrose 7y ago

One challenge with date based is that it can make your API seem old if it’s really stable. For example, see PagerDuty’s v1 events API: https://events.pagerduty.com/generic/2010-04-15/create_event.json https://events.pagerduty.com/generic/2010-04-15/create_event... Customers there would sometimes ask if that API was still relevant given its date is 9+ years old. In Shopify’s case, where there are quarterly version bumps and deprecation over time, date based makes better sense.