The problem with APIs

API is a tricky subject matter, no matter who you talk to. For business-folks, API downtime can be a source of revenue loss. Project managers worry about speed-to-market because of undocumented APIs. Architects and managers have to debate about the optimal way to implement any new requirement in an already complicated system. Developers lose sleep because of failing poorly-tested APIs.

Even after completing 3 years of designing and studying the API eco-system, I’m coming to terms with how less I understand. The API landscape, in particular, can be so tricky to understand because:

• Dynamism - APIs have evolved quickly over a relatively short period of time and continue to do so. While change is good, APIs tend to be more laggardish because of an interplay between API producers and API consumers. API producers want to push changes because of changing technologies, new requirements, or fixing security and performance concerns. Accepting change requires more work for API consumers. Therefore measures like versioning, deprecation comes into the picture leading to increasing complexity over time.
• Opaqueness - While every industry and most companies work with APIs, very few people openly talk about their APIs. Common design patterns are not commonly followed and everyone employs unique workarounds to manage APIs in their system. Things look simple behind several layers of abstraction but they’re not.
• Variety - Everyone agrees on this one. APIs are difficult, mainly because of the huge number of variables like technologies, protocols, patterns, tools, business use-cases, etc involved.