There Is No Single Right Way To Do APIs
My time working in the API sector has been filled with a lot of lessons. I researched hard, paid attention, and found a number of surprising realities emerge across the API landscape. The majority of surprises have been in the shadows caused by my computational belief scaffolding I’ve been erecting since the early 1980s. A world where there has to be absolutes, known knowns, things are black and white, or more appropriately 1 or 0. If I studied all APIs, I’d find some sort of formula for doing APIs that is superior to everyone else’s approach to doing APIs. I was the API Evangelist man–I could nail down the one right way to do APIs. (Did I mention that I’m a white male autodidact?)
I was wrong. There is no one right way to do APIs. Sure, there are many different processes, practices, and tools that can help you optimize your API operations, but despite popular belief, there is no single “right way” to do define, design, provide, or consume APIs. REST is not the one solution. Hypermedia is not the one solution. GraphQL is not the one solution. Publish / Subscribe is not the one solution. Event-driven is not the one solution. APIs in general are the the one solution. Anyone telling you there is one solution to doing APIs for all situations is selling you something. Understanding your needs, and what the pros and cons of different approaches are, is the only thing that will help you.
If you are hyper focused on the technology, it is easy to believe in a single right way of doing things. Once you start having to deliver APIs in a variety of business sectors and domains, you will quickly begin to see your belief system in a single right way of doing things crumble. Different types of data require different types of approaches to API enablement. Different industries are knowledgable in different ways of API enablement, with some more mature than others. Each industry will present its own challenges to API delivery and consumption, that will require a different toolbox, and mixed set of skills required to be successful. Your social network API strategy will not easily translate to the healthcare industry, or other domain.
With a focus on the technology and business of APIs, you can still find yourself dogmatic around a single right way of doing things. Then, if you find yourself doing APIs in a variety of organizations, across a variety of industries, you quickly realize how diverse your API toolbox and approach will need to be. Organizations come with all kinds of legacy technical debt, requiring a myriad of approaches to ensuring APIs properly evolve across the API lifecycle. Once a technological approach to delivering software gets baked into operations, it becomes very difficult to unwind, and change behavior at scale across a large organization–there is no single right way to do APIs within a large enterprise organization. If someone is telling you there is, they are trying to sell you the next generation of technology to bake into your enterprise operations, which will have to be unwound at some undisclosed date in the future–if ever.
I’ve always considered my API research and guidance to be a sort of buffet–allowing my readers choose the mix that works for them. However, I still found myself providing industry guides, comprehensive checklists, and other declarative API narratives that still nod towards there being a single, or at least a handful of right ways of doing APIs. I think that APIs will ultimately be like cancer, something we never quite solve, but there will be huge amounts of money spent trying to deliver the one cure. I’ll end with the comparison there, because I don’t want to get me on a rant regarding the many ways in which APIs and cancer will impact the lives of everyday people. In the end, I will still keep studying and understanding different approaches to doing APIs (both good or bad), but you’ll find my narrative to be less prescriptive when it comes to any single way of doing APIs, as well as suggesting that doing APIs in the first place is the right answer to any real world problem.