3 ms·
> as soon as existing clients break it's a new major version How do you know when this happens? You don't have integration tests with all of your clients. What
by UncleMeat 6y ago
> as soon as existing clients break it's a new major version
How do you know when this happens? You don't have integration tests with all of your clients. What if they break because of some insane dependency on your internal behavior. Let's say that they rely on your API taking >100ms to respond in all cases and you optimize things so now it returns in 50ms most of the time. Is that a breaking change?
Clients will always always always find a way to depend on every single observable behavior of your system. This makes everything a breaking change, given enough users.
- hinkley 6y agoIf you need to add a new field to your API, you probably have to add that field to your data model. So you start off by adding the field but not expecting any data. You might even ignore it. In order to do a migration, you are going to need a default value for that field, so you start storing the default value. You migrate existing records to contain the default. Then you start validating and storing the supplied value, with the default if it's missing. Next you add warnings to the defaulting logic. Eventually that warning becomes an error. Only near the end of this process can the rest of your code start making decisions based off of the new value instead of the old one (except in sanity checking exercises you perform along the way to verify that this is a choice and not a bug). Once that is done, you might start removing or ignoring the old value. What I think is often lost in technical discussions about APIs is that the above process has built into it a framework for talking to your customers about the change, whereas often the subtext of these migrations is "how can I use technology to avoid having to talk to people". Changing relationships without having an adult conversation with people is passive-aggressive behavior. You have a technical problem that has become a social problem. You can't fix it with technical solutions alone. Sack up and talk to people. Even, or perhaps especially, if you have a solution that requires little to no work on their part. Abstractions leak, people hate nasty surprises, and their follow-on questions most likely will bring up cases you never knew about or simply forgot. Having automation makes this conversation easier, but it doesn't obviate it.
- audron 6y agoYou gotta draw a line somewhere and I'd probably draw it in proximity to the documented behavior, and apply some superheated sanity to it while at it. Every change ever will upset somebody. And at the point where you have enough users you have better stuff to care about than some people that natural selection will get to sooner than later.
- mike_d 6y ago> You don't have integration tests with all of your clients Why not? Publish client libraries and test them. If someone makes a third party library or client, make sure it is appropriately documented as unofficial.