3 ms·

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

by n4r9 2y ago

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.

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

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