Affordance Aversion

We don’t dislike affordances because they’re too complicated to implement. We dislike them because they’re too complex to predict.

OpenAPI is a comfortable blanket. It gives you paths, parameters, status codes. The fullset of technical details. Everything looks predictable. But, among other things, it is static. If the world changes or your client needs to adapt dynamically your OpenAPI document drifts out to sync. Without regular care, your API metadata document becomes outdated a…