3 ms·

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

> 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 another fixed, stable API (your new one). Lock it down to only your old customers, if you want. The support costs will be basically zero, and your existing paying customers will thank you for respecting their time with a dependable, low-churn API.

n4r9 2y ago
What if the new API is more capable precisely because the parameters have been completely redesigned?
- cinntaile 2y ago
  Surely you can keep it backwards compatible AND give people access to the new good stuff?
  - smallnix 2y ago
    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.
    - AlotOfReading 2y ago
      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.
      - chipdart 2y ago
        > 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.
  - chipdart 2y ago
    > 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.
- taeric 2y ago
  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.
  - chipdart 2y ago
    > 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?
    - taeric 2y ago
      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-deprecation-policy-is-killing-you-ee7525dc05dc 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.
deleted 2y ago
[deleted]
tuyguntn 2y ago
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 your eng. org
- tuyguntn 2y ago
  also, the assumption here is "more capable = same features + something new (no removals)", sometimes you have to delete some features as part of new API (e.g. stop creating audit log entry for an action).
  - tikhonj 2y ago
    Conceptually, we should see deprecating a feature as a separate question from moving to a new API. So in this scenario, you would manage deprecating functionality in the same way regardless of whether you're also rolling out a new API at the same time.
- michaelt 2y ago
  > 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.
  - chipdart 2y ago
    > 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.
chipdart 2y ago
> 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.
- oasisbob 2y ago
  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-architecture-pattern https://www.redhat.com/architect/pros-and-cons-strangler-arc...
deleted 2y ago
[deleted]
gofreddygo 2y ago
And voila! Just like that, you now have 2 systems to maintain, support and debug. Do we redirect server side, use 302 or use JS to redirect ? docs and api dont match, users don't RTFM, but lament that the engineering quality is low. Support now needs to know which api endpoint the user with problems is hitting and why they cant repro when hitting the new endpoint. Auth will be fun too, is it a domain redirect? subdomain? Cert rotations anyone ?
- chipdart 2y ago
  > And voila! Just like that, you now have 2 systems to maintain, support and debug. It's even worse, the "new" system is a layered mess where logic is spread across multiple systems and services, and is bound to accommodate all the original scenarios and ensure new changes remain compatible across multiple versions. It's a far worse situation than keeping the old APIs in. It's a proposed solution from someone who clearly did not even read the problem statement.

n4r9 2y ago

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

cinntaile 2y ago
Surely you can keep it backwards compatible AND give people access to the new good stuff?
- smallnix 2y ago
  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.
  - AlotOfReading 2y ago
    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.
    - chipdart 2y ago
      > 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.
- chipdart 2y ago
  > 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.
taeric 2y ago
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.
- chipdart 2y ago
  > 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?
  - taeric 2y ago
    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-deprecation-policy-is-killing-you-ee7525dc05dc 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.

deleted 2y ago

[deleted]

tuyguntn 2y ago

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 your eng. org

tuyguntn 2y ago
also, the assumption here is "more capable = same features + something new (no removals)", sometimes you have to delete some features as part of new API (e.g. stop creating audit log entry for an action).
- tikhonj 2y ago
  Conceptually, we should see deprecating a feature as a separate question from moving to a new API. So in this scenario, you would manage deprecating functionality in the same way regardless of whether you're also rolling out a new API at the same time.
michaelt 2y ago
> 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.
- chipdart 2y ago
  > 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.

chipdart 2y ago

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

oasisbob 2y ago
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-architecture-pattern https://www.redhat.com/architect/pros-and-cons-strangler-arc...

deleted 2y ago

[deleted]

gofreddygo 2y ago

And voila! Just like that, you now have 2 systems to maintain, support and debug. Do we redirect server side, use 302 or use JS to redirect ? docs and api dont match, users don't RTFM, but lament that the engineering quality is low. Support now needs to know which api endpoint the user with problems is hitting and why they cant repro when hitting the new endpoint. Auth will be fun too, is it a domain redirect? subdomain? Cert rotations anyone ?

chipdart 2y ago
> And voila! Just like that, you now have 2 systems to maintain, support and debug. It's even worse, the "new" system is a layered mess where logic is spread across multiple systems and services, and is bound to accommodate all the original scenarios and ensure new changes remain compatible across multiple versions. It's a far worse situation than keeping the old APIs in. It's a proposed solution from someone who clearly did not even read the problem statement.