I've browsed resources about API design on the web lately and I was rather surprised that I haven't seen a single mention of the most important thing to know about APIs. And by "most important" I don't mean "covers 20% of the topic" but rather "solve it and the rest of it can be done by a monkey" sort of thing.
Here it is: API is a POLITICAL concept, not a technical one.
Arguing that API is a technical problem is like arguing that state borders are a geographical phenomenon.
Yes, boundaries often coincide with rivers and mountain ridges. But often they do not. And what really matters is that they are established by political processes ranging from peaceful negotiation to outright war.
Similarly, API (including network protocols and such) only happens when there are different human groups involved in building software.
Think about it: APIs are just functions, n'est-ce pas? So how come that you don't consider that little helper function you've written yesterday to be an API? And why are those functions that you share within your team a bit more API-like, but still not real APIs? And why are the functions used to communicate between departments almost definitely APIs and those exposed to the external users are undisputable and full-blown APIs?
Because "API", let's face it, is just a techie way to say "political boundary". It's used to separate "I am responsible for this" from "you are responsible for that" and "I will get money/credit for this" and "you will get money/respect for that".
But does it really matter? Would the API design process be different if we acknowledged the fact?
Yes, it would.
Programmers typically don't like politics and tend to argue using technical language. But that doesn't make politics go away, it just makes it subconscious. In fact, I am tired of people pushing their political agenda under the disguise of technical argument. And the fact that they honestly believe that they are being unbiased and strictly technical doesn't make it better. It makes it worse. It also results in messy APIs with ragged borders and undefined "disputed areas" in places where political consensus wasn't reached.
Can we make it better?
Yes. But we first have to acknowledge that what's really going on is a dispute about power, money and respect. Only then we can settle that dispute first and move to technical stuff later. Actually, once the political dispute is over, technical design should be fairly trivial.
Acknowledging the political nature of APIs also provides insight into the dynamics of the design process. Commercial entities typically want to grab more land. Open source developers working for free want their area to be somehow smaller to avoid too much work. In general, everybody wants to get rid of high cost/low return areas and exercise control over low cost/high return areas. People who are actually working with the technology want the boundaries to be as short and well-defined as possible to minimise friction between the groups. People who do sales or politics for living, on the other hand, want the borders to be long, ambiguously defined and convoluted. They thrive on friction and so they create it.
I know that it's hard to get rid of the stereotype of API being a technical matter and to train yourself not to jump to the technical argument before the political issues are solved. However, if you do so, you'll save yourself many a headache and you'll also make the world a better place for the rest of us.
July 28th, 2015