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

31–40 of 60 posts

Re: Deactivating an API, one step at a time

#31

Post by chipdart »

michaelt wrote: post #3

> It might be that you want to replace it with a new, more capable version If you're truly replacing your API with a new, more capable version there's a much better option, in my experience. Roll out your new API, and replace your old API's implementation with a proxy that calls through to the new API. The proxy will need very little maintenance, as all it's doing is connecting one fixed, stable API (your old one) to…

> 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 extra maintenance work to keep around a specific configuration in an API Gateway if your goal is to get people to stop using it so that you don't have to maintain N+1 versions of your service. 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 mean, even changes in performance can be disastrous. And even under the unlikely case a API Gateway applying a transformation is enough to sunset the old version,how is that an improvement on maintenance? You now have a new abstraction layer that requires testing and maintenance, and a multitude of scenarios you need to validate independently whenever a change is made. And what answer do you have to the question on what to do if a commit works in the new version of the API but introduces a regression on the old version?

The truth of the matter is that there are only a couple of sunsetting strategies that work, which is:

* In internal service calls, negotiate a sunsetting strategy with other internal teams. The deadline will invariably be pushed forward each and every single time.

* In external service calls, you can announce to the world you're sunsetting the API and advertise it on Times Square,and still a hefty share of your customer base won't know and will still be caught by surprise. The only strategy that works is graceful degradation: start returning 404s and 410s periodically and dial it up until clients feel the need to move on. Dial it back when appropriate to get your point across without denying service, but understand that it will be impossible for some clients to change.

Re: Deactivating an API, one step at a time

#32

Post by bornfreddy »

its_ethan wrote: post #12

It would be really cool to see a graph of the API usage over time with markers showing when each "stage" was occurring. I'm wondering if there were significant dips shortly after each stage, or if it was more of a gradual decline? It would also be interesting to know if the API was still being used up until the final stage? Were there any ramifications/ angry customers at the door after that?

Given the timeline of just 4 months, I would expect 90% of customers not migrating in time. The percent of those who migrated to the new API after that depends on how vital this service is to them, it would be interesting to see the rate of lost businesses. I know that if a service provider did this to me, I would prefer migrating to their competition, all things being equal.

Re: Deactivating an API, one step at a time

#33

Post by smallnix »

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?

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.

Re: Deactivating an API, one step at a time

#34

Post by oasisbob »

chipdart wrote: post #31
michaelt wrote: post #3

> It might be that you want to replace it with a new, more capable version If you're truly replacing your API with a new, more capable version there's a much better option, in my experience. Roll out your new API, and replace your old API's implementation with a proxy that calls through to the new API. The proxy will need very little maintenance, as all it's doing is connecting one fixed, stable API (your old one) to…

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

The post you're replying to is describing a straightforward implementation of the strangler pattern.

It's a valid and useful technique. Even if you disfavor it, I don't see why you feel the need to judge the comprehension skills of the commenter.

https://www.redhat.com/architect/pros-and-cons-strangler-arc...

Re: Deactivating an API, one step at a time

#35

Post by lazyasciiart »

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.

We have customers using a client that was officially deprecated in 2020 and stopped working altogether for six months in 2022, along with as much announcement noise as we could make. A year later I was surprised to realize the environment change that had blocked it was gone…and people were still using it.

Re: Deactivating an API, one step at a time

#36

Post by lazyasciiart »

chipdart wrote: post #30
petesergeant wrote: post #9

> In addition to offering human-understandable communication, I asked the API producer to add the Deprecation HTTP header field to all responses Cute, but, I question the value

> Cute, but, I question the value I came here just to say that. What an half-baked idea. It might be trivial to mindlessly bolt on response headers, but if the goal is that the mechanism needs to be impactful and have consequences then the response header is a big red herring as you're actually relying on clients to implement support for sunsetting the endpoints. If that's the case then you already have meaningful me…

> If that's the case then you already have meaningful mechanisms, such as passing this sort of metadata in responses to requests for the root resource. This is something that pretty much any HATEOAS spec already supports.

Yes, they support it with headers.

Re: Deactivating an API, one step at a time

#37

Post by compootr »

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.

Yes, and you should do this after being honest that it's being sunsetted

Set a date it'll be 100% available until then begin degrading it. After all, you didn't guarantee 100% availability/usability after said date

all this to say, if you release both versions, I'd monitor adoption and keep v1 alive if a lot of customers (esp. big spenders/enterprises!) depend on it

Re: Deactivating an API, one step at a time

#38

Post by compootr »

bpedro wrote: post #21
petesergeant wrote: post #9

> In addition to offering human-understandable communication, I asked the API producer to add the Deprecation HTTP header field to all responses Cute, but, I question the value

Great question. As a consumer, you can set up an alert when any of your API requests has a deprecation or sunset HTTP header. You'd know immediately if any of the APIs you depend on is about to be deactivated.

You're assuming downstream companies will parse & utilize this header

If they were competent enough to do that, they'd probably pay attention to updates sent via, say, email. Brownouts would make people notice, like "oh shit, $API doesn't work!"

Re: Deactivating an API, one step at a time

#39

Post by AlotOfReading »

smallnix wrote: post #33
cinntaile wrote: post #20

Earlier quoted context omitted.

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.

Re: Deactivating an API, one step at a time

#40

Post by michaelt »

chipdart wrote: post #31
michaelt wrote: post #3

> It might be that you want to replace it with a new, more capable version If you're truly replacing your API with a new, more capable version there's a much better option, in my experience. Roll out your new API, and replace your old API's implementation with a proxy that calls through to the new API. The proxy will need very little maintenance, as all it's doing is connecting one fixed, stable API (your old one) to…

> 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 promise. If I make incompatible changes to the API I'll break their stuff and they'll be understandably mad at me.

All I have to do, therefore, is write an adaption layer that adapts the V1 public API which is stable and never needs any new features or fields because it's deprecated to the V2 public API which is also stable because fields and methods do not disappear on public APIs.

I don't know what an "API Gateway" is - given that you seem to think it's a lot of work to set up and maintain and that it can't accomplish this task, it's probably not the right tool for the job?

Post reply on HN