Hacker News Reader

Comment by n4r9 | Hacker News Reader

What if the new API is more capable precisely because the parameters have been completely redesigned?

The presumption would be that there is a mapping from the old parameters to the new? Not necessarily a simple shift/rename, but you aren't doing your users any favors if they have to speak an incompatible vocabulary to make use of the new system.

> The presumption would be that there is a mapping from the old parameters to the new?

"Presumption" is a funny word when used to say you didn't considered the part which happens to be the cornerstone of the whole proposal.

You can't just hand wave over the core part of the whole proposal, and just say "well I expect it to somehow already be working and serving it's purpose", specially when the question is on what happens when this mapping is either practically or theoretically impossible.

Just think through the problem and consider small mundane details such as the fact that the decision to create a new API version is never taken lightly, and different API versions are created to accommodate breaking changes. Think about problems such as: what if resource IDs are incompatible and entirely different? On top of that, what if the old API returns references to different resources than the new API? How do you solve that with "mapping"? Are you suggesting we roll out a mapping service?

If you are making a new API that cannot serve the needs of older users, then you are basically saying to your old users that you would rather they leave. At the least, you are signalling that you are inclined to give them more work. Don't be surprised when they decide that their migration isn't from your old service to your new one, but from your old service to a competitor.

Note that this is not the same as saying, "if you want to use the new features, you have to do the work to tell us more about what you are doing by using the new api." More, you can have some restrictions. But, at large, the view you are espousing reminds me of the blog by Yegge about Google's deprecation policy. (Link: https://steve-yegge.medium.com/dear-google-cloud-your-deprec...).

I'm sympathetic to the idea that some APIs are terrible and are best redone. I have seen far too many redone APIs that do not service existing user's needs and that resolve into a complete disaster. In almost all cases, it is because the team doing the work thought that it was best to offload all thoughts of how to migrate onto every other team that was calling to them. You think it would be a lot of work to make a facade/proxy/whatever you want to call it layer. You aren't wrong. But largely what you have done is shifted that work to every single caller you have.

It depends... let's say you're the leading product in the area, your users are devs, and there's a good reason behind the change, then you're probably okay to deprecate APIs. For example, NUnit has now deprecated the "Assert.AreEqual" method: https://docs.nunit.org/articles/nunit/writing-tests/assertio... . For me this meant running through hundreds of tests and rewriting them using "Assert.That" or sometimes using "ClassicAssert.AreEqual". I guess I see it as part of the job of being in an evolving industry.

Library deprecations are fairly different from service deprecations. That said, same points generally stand. I know MANY people that no longer use Guava because they got tired of how rapidly they had to update their code due to changes in the library. Similarly, I know very few people that have gotten upset with the deprecation policy of Java core.

Surely you can keep it backwards compatible AND give people access to the new good stuff?

Not if the API reflects a fundamental change in flows. E.g. not fun to proxy a sync API into the new async one which splits a single operation into three.

That's a reason not to make fundamental changes to your flows, but the example given isn't that difficult. It's probably how the developer on the customer's side is going to deal with the issue, so you may as well do it for them. Trying to convince any meaningful percentage of customers to rewrite fundamental aspects of their existing integration to support your product roadmap isn't going to happen, so don't expect it.

> That's a reason not to make fundamental changes to your flows (...)

You're somehow assuming the engineering teams involved in making these decisions don't think through these issues and just jumpstart changes to critical parts of their business without any thought or consideration.

In the meantime, engineers need to work in the real world, with real world requirements and constraints. Often enough, these include introduce breaking changes, such as changes to workflows.

It is entirely unhelpful to lay grand claims based on your ability to wish whole problems away. Don't like catching a flu? Well, that's a reason to not get sick. Insightful.

> Surely you can keep it backwards compatible AND give people access to the new good stuff?

New API versions are not rolled out lightly. You roll them out only when you cannot give access to the new stuff while preserving compatibility.

Otherwise you'd just update/extend the old version.

Reply on news.ycombinator.com