We work in small teams on a few apps that all rely on one central API, which is also developed in-house. The team working on this API is composed entirely of senior developers.

With every rollout of substantial changes, all app teams are asked to do a full regression test and report problems (if any).

Common knowledge dictates that this is the ultimate situation to use API versioning; the app specifies on which version it relies, and it can then be updated whenever the need is there. Updates to the API should not break existing applications. This would also make rollouts easier and quicker.

The idea of API versioning has been brought up with said team before, however, only to be dismissed as 'Versioning will turn into a mess'. And I agree that API versioning isn't the solution to all problems, but I think it could substantially improve our release process.

To me, this sounds mostly like an architect decision; however, we don't have anyone in the architect role. Most parties involved (PU, QA) seem to not really see the benefits of API versioning either. This is ridiculous to me, as it's an industry standard way of working. It reminds me of people who use dropbox as a VCS.

What is the best way to push, within my means, and without making it seem as if I'm trying to do the other team's work?

  • Aside from their own unwillingness to adapt their code to use the most up-to-date API, what genuine reasons have been given for versioning turning "into a mess"? What position do you have within the teams mentioned? – user34587 Mar 6 '19 at 11:00
  • 2
    all app teams are asked to do a full regression test Do you have evidence that lack of versioning causes you undue grief? – rath Mar 6 '19 at 11:08
  • Common knowledge dictates that this is the ultimate situation to use API versioning I don't want to argue if this can be called common knowledge (I have my opinions, but it's not important). Either way, you don't persuade people with it's an industry standard way of working, you persuade people with what can your suggested practice benefit them in detail. – tweray Mar 6 '19 at 14:37
  • Well it could get messy if you have several apps that are all on different versions, and they refuse to update their code to use the latest. Especially if the reason for the new version of the API is a security flaw or major bug. Not having versioning forces them to use the most up-to-date API and allows the developers to focus on one set of code and not worry about people using older versions. – Smock Mar 6 '19 at 15:58
  • It's hard to see how this can become anything but an argument over technical merits dependent on context details known only to the asker and their co-workers. – Chris Stratton Mar 6 '19 at 18:15

It is not obvious from your description that API versioning is necessary or wise in this particular scenario. I'm guessing the need is not clear to the other engineers that you are talking about, either. And phrases like "common knowledge" and "industry standard" are kind of code for "other people do it so we should too," which is an argument from authority that is rarely persuasive by itself when you need to convince other people to do something you want them to do.

What you need to do if you really want to do this, is start by identifying a specific problem you have right now, and then build the case for API versioning on that. An example:

We spent ## hours last month rewriting App A because API changes broke everything. Because we spent ## on that, we weren't able to add Feature Z for Customer Y and missed out on $X in revenue. Instead of breaking our API, if we had versioning, we would have spent 5 minutes on the API change, completed Z, and made $X + W because we were able to get a head start on Feature V.

Note that, this justification is not abstract at all; it depends entirely on things that are measurable. All of the measurable things are things that a non-technical manager can understand: money, time (which is money), billable features (which could be turned into money depending on what your business model is).

As a "senior engineer", I don't want to maintain multiple API versions ever, because that's lots of work I don't want to deal with. As "guy who does what my boss tells me", I'll totally bend over backwards if my boss tells me that we need to maintain multiple versions to save a nontrivial amount of money.

| improve this answer | |

From the details you gave, it is hard for me to tell whether you are right or wrong. But I will try to answer your question:

What is the best way to push, within my means, and without making it seem as if I'm trying to do the other team's work?

Very little as it looks, as deciding on the versioning (or lack thereof) to me seems like part of the teams work. But if you still want to try to persuade them here are some suggestion:

  • Don't refer to "common knowledge", if it was common knowledge everyone would already agree with you

  • Be ready to be wrong. There is a team of seniors working on the topic full time all having a different opinion than you, you are actually very likely to be wrong.

  • Try to understand why the choice was made and what problems the seniors anticipate

  • Describe your problem case (the reason why you need versioning) as good as possible and your homework to find out whether there is any other solutions for your problem.

  • Figure out other teams would gain from implementing versioning

Then you bring all your research together in a case how versioning might benefit the company (be ready to present numbers), how the biggest concerns against versioning might be addressed and with what effort it can be implemented and maintained.

If you are not just open for someone else to change your mind, but actively working towards it and nobody has changed your mind while you were collecting all the research, you are very likely to be right and others will not be able to disagree :)

| improve this answer | |

This is one of those spend time now to save time later scenarios. The people that calculate costs rarely consider future savings because they expect them not to materialize. They usually only ever want short term savings. As a result, you're forced to write quick bad code, and bandage it up every subsequent version.

This will lead to rather hilarious but frustrating scenarios where you will see code like this

var oldDate = api.convertDateTime(input);
//.....some code
var newDate = api.convertDateTime1(input, format);
//.....some code
var finalDate = api.convertDateTime2([oldDate, newDate], format);

And the reason is simple, no one wants to look back and see where api.convertDateTime was used and fix any usages, so they make a new version. But there is no difference in what it does, so you get a number. Then later, it happens again, someone wants to add a format, and it's required, but they don't want to go back and fix all old usages, so they make another new version. And finally, someone wants to convert multiple dates in 1 line, so they make another new version and again don't want to regression test every old usage, so again, another new version.

And thus, a bad version of API versioning is born.

So, how to avoid this? You have to convince people that spending time now, will avoid the mess that I just described. This is not an easy thing to do and it plays heavily into the company culture. It also matters greatly if your department is a cost centre or a profit centre. A profit centre is often allowed to plan ahead. A cost centre tends to be required to keep costs as low as possible each year, no matter how much technical debt you accumulate.

So your argument is simple:

You need to show some examples of versioning gone wrong.

Show some examples of better versioning.

And, most important, graph the time cost between the methods so that yours looks cheaper in the long run. If you come armed with numbers, you won't be ignored.

In my experience, a compromise is usually made, where a first version of the API is built, and then a versioning system is built in afterwards under the idea that initially there will be too many versions to keep track of, so wait for the API to stabilize and mature before worrying about versions. Time is then spent upgrading all old API usages to provide a version once one exists, or any usages without a version specified are assumed version 1.

| improve this answer | |
  • Never materialize or hard to quantify? Had one the other day, make 30 database models. First took 10 hours. 29 took seconds, why? Because i was able to make a future process for it. Over 1000 models now exist in 2 weeks. Models usually take a half hour each manually. So what's the savings? And a bonus is now all models are consistent no matter which developer builds them. So future savings do often materialize, but in unexpected or difficult to calculate ways. Which is why my answer focuses on calculating them. – Trevor Mar 6 '19 at 19:38
  • @JoeStrazzere Gotcha, I edited my answer to include that – Trevor Mar 6 '19 at 20:24

Instead of worrying about a particular solution to your problem (i.e. versioning), focus on what uptime / change management principles you need the API to meet. It's fair to say that API changes should never break any client application by surprise, that the API should have very little downtime, and that any breaking changes to the API are advertised as far in advance as possible.

If you can agree on these principles, then let the API developers (or the group) decide how to meet these goals.

| improve this answer | |

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .