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.
Martin Sústrik, July 28th, 2015
The issues you discuss are real, and something being realized and worked on by many. Your title is linkbait. ;-)
Politics of APIs - http://apievangelist.com/2014/03/17/politics-of-apis/
Politics of the API Economy - http://apievangelist.com/2015/07/27/politics-of-the-api-economy/
API Evangelist Thoughts On The Right To An API Key And Algorithmic Organizing - http://apievangelist.com/2014/09/06/api-evangelist-thoughts-on-the-right-to-an-api-key-and-algorithmic-organizing/
I don't believe need to stop kidding ourselves about APIs, we need keep having discussions about why they work, why they don't, and the common building blocks that make things go around.
Something I've been working on for over 3 years.
Kin Lane
Hi, good to know that there's someone out there who thinks about the problem. It's not at all that common.
Anyway, it'll be hard to decompose politics into building blocks. Any system proposed will be gamed if it gets adopted. That's the nature of politics, I am afraid.
Hi author,
In your first sentence:
You go on to talk technically about how:
and then how there can be
So it would seem that you are pretty focused on building APIs and API design.
API design is 0% political and 100% technical. How APIs are exposed, how they are organized, how they are developed, how they are documented - it's all technical - 0% political.
The 100% political part happens at the product level where you have stakeholders pushing and pulling with each other on who the API is for. This is not API design. None of the product (political) stakeholders will tell any of the engineers how the design should look - because that's a technical issue.
This is the least responsible statement in your article:
If all product politics surrounding an API are wiped out, I can guarantee you 100% that an API will not, and cannot, be properly designed and implemented technically by a monkey or even a junior developer for that matter.
A political argument if I've ever heard one.
We make them "difficult" to push political agendas. You've proven this by saying "a junior developer" can't do it. Absolutely playing into the concept of this post, as it is about power and money.
APIs aren't hard. Stop pretending they are.
Well, that's how it should be. Solve the political problem, then design the API based on that. But unfortunately, that's rarely the case.
As for the monkey part, yes, it's an exageration. But let's be frank: It's not quntum physics. If you've been programiing for a decade or two you can probably hack together a bearable API. Assuming that the political aspect have been settled in advance, of course.
If you have "a decade or two" years of experience doing something I would hope you would be able to do it pretty well…
Apparently a decade or two years of experience and previous API design experience makes us 'monkeys'. Going to update my resume now: 10 years experience with APIs, qualified monkey
Could you provide some proof that for all APIs ever designed, it's rarely the case that during implementation, engineers have to deal with political, product decisions? It's all dependent on the organization you work with.
So I'm going to assume that for APIs you've had to deal with, the product and engineering roles overlapped. That is most definitely not the case for all APIs. I guarantee you that at the Top 100 companies that have developed a public SDK/API the Engineer(s) have made zero Product decisions when implementing and designing the final API.
It's not rare for the entirety of API's that have ever been designed - It's rare for the entirety of API's you have designed.
Write your rebuttal post, dude. Your flames aren't actually illuminating anything, they're just setting the roof on fire.
I understand the OPs prospective and strongly agree with it.
Great post!! Can you recommend good resources that you came across re:API design?
The most critical rule, IMO, is the "rule of three".
But there's a lot of other rules (of thumb) to follow. This is quite a good presentation: http://lcsd05.cs.tamu.edu/slides/keynote.pdf
Post preview:
Close preview