Hacker News Reader

Comment by mlthoughts2018 | Hacker News Reader

mlthoughts2018

They might become part of the API in a superficial sense, but if you broadcast clearly that undocumented behaviors are subject to change, then users can decide if they want to accept that risk and won’t have a valid complaint if they want the not-covered-by-the-contractual-API preserved or become surprised by a change.

View on HN

> if you broadcast clearly that undocumented behaviors are subject to change, then users can decide if they want to accept that risk

That sounds nice in theory, but doesn't really work in practice. If you're building infra and a core piece of your company's product relies on these undocumented behaviors, you can't just change the behavior and shrug your shoulders when the whole product breaks. Similar if you're providing an external API to users/customers, you can't just break their stuff without worrying about it.

Isn't this the exact reason people came up with semantic versioning?

I'd add, if the API is meant to implement a protocol but doesn't implement it quite correctly, you may object to the misimplementation, but if your code has to work with the implementation, you have to adapt to their bug. It's not even a matter of undocumented behavior.

Experienced recently as a consumer of an API when letsencrypt made a breaking change to implement the protocol correctly. Broke my code which relied on their original incorrect implementation.

While you might not view their complaint as valid, what if the change you made cuts off service to the customer? And what if the service you provide is in the critical path for the customer, such as hosting, payments, or even power?

I can testify to this personally, having worked at a payments processor and accidentally broken integrations. The business, as it should have, had little tolerance for me changing a depended upon API, even though it was not documented

The struggle here is that it's not always clear what behavior, buggy or not, is intended behavior. Especially as the complexity of an API endpoint or method increases, for example with large input models or mutable system state at the time of request.

Too many devs do not read the spec/docs and relies on testing. If it works it's golden.

Of course, that doesn't mean they won't complain.

Reply on news.ycombinator.com