Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Deactivating an API, one step at a time

apichangelog.substack.com

Post reply on HN
Print view View original

51–60 of 60 posts

Re: Deactivating an API, one step at a time

#51

Post by chipdart »

michaelt wrote: post #40
chipdart wrote: post #31

Earlier quoted context omitted.

> Roll out your new API, and replace your old API's implementation with a proxy that calls through to the new API. I don't think you understood the problem you're commenting on. The problem is not that you have a new fancy API version you expect users to consume. The problem is that you need to shut down the old API without causing customer or business impact. It makes little to no sense to pile up technical debt and…

> Your vague observation of how much work a API Gateway config takes is meaningless because you have no idea the impact of any change to the API will have on the older version fed through adapters. I don't think you've understood what I'm proposing here. When I release the V2 public API and invite my customers to code against it, they're going to start calling the methods I offer and expecting the response fields I p…

I don't think you figured out the point I presented you.

The whole point is that new API versions are rolled out because the changes that need to be introduced are incompatible with old APIs. Otherwise there won't be a need for a new API, is there? The whole reason there are different APIs is that they are already incompatible. If you could handle new usecases with adaptors, you'd already be using them. But you aren't.

> I don't know what an "API Gateway" is

Right, and here you are lecturing on API design and present solutions to API problems.

Re: Deactivating an API, one step at a time

#52

Post by chipdart »

cinntaile wrote: post #20
n4r9 wrote: post #18

Earlier quoted context omitted.

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

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

> 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.

Re: Deactivating an API, one step at a time

#53

Post by chipdart »

AlotOfReading wrote: post #39
smallnix wrote: post #33

Earlier quoted context omitted.

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…

> 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.

Re: Deactivating an API, one step at a time

#54

Post by chipdart »

michaelt wrote: post #47
devin wrote: post #44

Earlier quoted context omitted.

An assumption you're making here that you can even write an adapter layer for the V2 API. There may be things you wish to _remove_ in the V2 API. V2 does not always mean "add more stuff", it can often mean rethinking "what stuff" is provided.

Yes - that's why I included the proviso "if you're truly replacing your API with a new, more capable version" If your intention is to remove features and fire the customers who are relying on them, that's a different matter.

> If your intention is to remove features and fire the customers who are relying on them, that's a different matter.

No. That is not a different matter. That's basically the whole problem being discussed, and the topic of the blog post you're discussing.

Re: Deactivating an API, one step at a time

#55

Post by chipdart »

michaelt wrote: post #42
tuyguntn wrote: post #27

Earlier quoted context omitted.

This sounds a good idea in theory, but not sure about in real world. Consider having 4 versions of API, will you create 3 levels of proxies or each time re-write your old proxy? Sometimes, more capable mean additional side effects not existing in old contract (e.g. send an email about order), in that case your new API should be flexible to accommodate configuration of side effects, adding more maintenance cost to you…

> This sounds a good idea in theory, but not sure about in real world. > Consider having 4 versions of API, will you create 3 levels of proxies or each time re-write your old proxy? In the real world if you insist on breaking your paying customers' processes and products over and over again, pretty soon you won't have any paying customers any more, and you'll be free to make incompatible changes as often as you want.

> In the real world if you insist on breaking your paying customers' processes and products over and over again, (...)

You do not break anyone's experience by releasing a new version that's voluntarily adopted by your paying customers.

You are also somehow inexplicably assuming that your paying customers didn't ended up being paying customers because you adapted to customer demands and added the value that was important enough to them that they decided to pay for it.

I can tell you for a fact that there are paying customers for APIs that pay to use both the latest API and older versions. More often than not, they still consume old versions because they cannot spare the manpower to update some clients/services.

On top of that,the problem grows a few orders of magnitude when you open your APIs to the public. Even when you control the only clients to your APIs, it's impossible to get some end users to upgrade their software. Some still run old OSes that have long been unsupported, and some are even physically unable to run updates.

Re: Deactivating an API, one step at a time

#56

Post by tuyguntn »

michaelt wrote: post #42
tuyguntn wrote: post #27

Earlier quoted context omitted.

This sounds a good idea in theory, but not sure about in real world. Consider having 4 versions of API, will you create 3 levels of proxies or each time re-write your old proxy? Sometimes, more capable mean additional side effects not existing in old contract (e.g. send an email about order), in that case your new API should be flexible to accommodate configuration of side effects, adding more maintenance cost to you…

> This sounds a good idea in theory, but not sure about in real world. > Consider having 4 versions of API, will you create 3 levels of proxies or each time re-write your old proxy? In the real world if you insist on breaking your paying customers' processes and products over and over again, pretty soon you won't have any paying customers any more, and you'll be free to make incompatible changes as often as you want.

> In the real world if you insist on breaking your paying customers' processes and products over and over again, pretty soon you won't have any paying customers any more

Business 101, your profit is in higher margin or lowering your spending/cost. If your business is stable and making money your customers feel safe and are happy.

Deprecation lowers your cost (system complexity, less maintenance, dev time -> new features, new revenue streams). If you have an almost infinite resources then of course why not, you can support all possible API versions (there are few companies who can afford it and doing it at scale, AWS and Win32 APIs)

Re: Deactivating an API, one step at a time

#57

Post by chipdart »

Suppafly wrote: post #14
athenot wrote: post #10

Other strategies that could come in handy before completely shutting down the API: - Rate-limit the API, with increasing aggressiveness until you're down to 0 requests per unit of time; - Introduce latency in serving the requests (assuming your edge can handle the increased volume of open connections). Both of these introduce gradual degradation of the old API, without outright killing the business functionality that…

Man I really hate the idea of "Let's make a thing that works shittier so that people switch to the new thing". If you're in a situation where you have customer's just be honest about the changes coming and give them enough runway to get the changes made.

> Man I really hate the idea of "Let's make a thing that works shittier so that people switch to the new thing".

You're conflating sunsetting old services with forced upgrades. Degrading services when preparing for sunsetting the service is a surefire way to convince product managers to bump up migrations in their priority queue. Announcing sunsetting doesn't work. Reaching out directly to stakeholders doesn't work. What works is the urgency of avoiding downtime. The alternative is simply pulling the plug on a fixed date, which is not preferable.

Re: Deactivating an API, one step at a time

#58

Post by taeric »

chipdart wrote: post #50
taeric wrote: post #24

Earlier quoted context omitted.

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 ha…

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.

Re: Deactivating an API, one step at a time

#59

Post by n4r9 »

taeric wrote: post #58
chipdart wrote: post #50

Earlier quoted context omitted.

> 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 ha…

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,…

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.

Re: Deactivating an API, one step at a time

#60

Post by taeric »

n4r9 wrote: post #59
taeric wrote: post #58

Earlier quoted context omitted.

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,…

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 "…

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.
Post reply on HN