I used to believe there was a right way to do APIs. I don’t anymore. I know better. I’ve seen too many APIs. I’ve seen too many people get frustrated that we didn’t do the API in the right way. Anybody claiming to have the right way is selling you digital moose diarrhea. The right way to do an API is less about the API, and everything about the process, and who you have involved in producing and consuming the APIs. For technologists it is hard to see the process and the people and it is easy to just focus on the technology—–a mistake I see made over and over in the world of APIs.
I love producing detailed lists and visualizations of what it takes to produce and operate an API, only to have most people push back on claiming it is a waterfall or some made-up complexity, when it is just a mapping of the reality on the ground. In my experience the complexity of an API is rarely technical, and almost always about the people negotiating for an API on both the producer and consumer sides.
I am confident there is no right way to do an API. There is only the right way negotiated in any particular moment by a group of producer and consumer stakeholders who have skin in the game. As a recovering technologist and former believer I have found it easy to get caught up in obsessing over there being a right way-—when in reality the right way is always fleeting. The right way of doing an API is a balance and velocity achieved over time through the meaningful negotiation of versions of an API by producers with consumers.
The right way of doing an API is all about the process of producing and consuming an API, and the accumulated contract that works for everyone involved in a particular moment. It really isn’t even the API contract–the contract just happens to be the negotiated human and machine readable representation of what is right (or wrong). This right way is likely to not have been the right way 5 years ago, and may not be the right way to do it in the next five years. This is why I am a champion for the people and the process these days over any particular protocol, pattern, or specific technical approach to producing and consuming APIs.
