Let's stop kidding ourselves about APIs
250bpm.com
250bpm.com
What does this API do? Can I invoke it using my preferred language? What performance characteristics does it have? Is it synchronous or asynchronous?
To that we can add questions about types, latency, protocols, and so on.
But there are plenty of non-technical questions: can I rely on this service to continue operating in the future? Can I be sued for using it, or for using it in certain ways? Can I build a commercial service using the API or the data it provides? If the API provides me with data that is incorrect, or illegal (containing copyrighted material, say), who is liable? What likelihood is there that the people running the service will degrade or shut down the service, demand increased payment for access to it, or offer preferential access to my competitors? Who owns, controls or distributes any data that I share via my invocations of the API? And what happens if or when the answers to any of these questions change, and how can I influence the direction of those changes?
Whether you call these 'political' questions or not is a matter of semantics. I think they're political in the sense that they're about the people running the service, rather than the technology itself. They're about who controls it, who decides the direction of its evolution, and what constraints they operate under. Those questions will depend on business, ethical, regulatory and philosophical considerations, and I don't think it's unreasonable to describe those as being 'political'.
* Language bindings: The decision to create and maintain an API binding in a particular language is mostly a political decision based on what your API consumers want. It is a trade-off between convenience for the consumer and extra work for the API developers. You will probably develop bindings for popular languages. But what if a language is very popular but also one that developers are unfamiliar with, so it would be a high cost to learn the language and develop the binding? Both the developer and the consumers are invested in the resulting decision, which makes it political.
* Performance characteristics: This can be political as well, because in a sense it's a negotiation between the developer and the consumer. How much extra work should the developer do to save the consumer some time? How much of the computation should be done "behind" the API, and how much should be pushed onto the API consumers?
* Protocols: Each protocol has costs and benefits for the API developers and for the consumers. For example Apple chose to expose their push notification service over TCP, not HTTP. This has costs for the consumers because now they have to use a 3rd party library to handle a new TCP protocol (or implement it themselves). On the other hand, Android's push notification service uses HTTP POST, which is more developer-friendly. I would argue this is a political decision (and a deliberate one on Google's part).
* Latency: Typically reducing latency costs the API maintainers more dollars, but it makes the consumers' applications more performant. This is also, in my eyes, a case of a political negotiation. How fast can we make it so that consumers are satisfied, while spending the least money? Or from the consumer's perspective, how much latency is "acceptable"? This embodies a political trade-off as well.
You could probably make similar arguments for almost every other API characteristic. The simple fact is that almost everything that involves multiple people with selfish interests is at least somewhat political.
With a library, it is presumed (leaving aside the question of licensing, which is definitely political) that the decision about whether to use a library is purely technical: does it do the things we want it to do, with the correct level of performance, reliability and ease of use? You could imagine writing a test suite to determine definitive answers to these questions and, once answered, there would be no need to examine them again.
An API gives you access to someone else's product, and that product will evolve. Some of those evolutions may cause your product to break. If you're a Windows application developer, you can count on a pretty strong guarantee from Microsoft that they won't break Windows APIs, which is why programs from the 90s still run on modern versions of Windows, even if this requires some complex engineering from Microsoft. There was no technical aspect of the Win32 API circa 1995 that guaranteed these things; the commitment to future support was entirely political in nature.
The same applies to network-accessible APIs today. If your program achieves some result by invoking a statically-linked library, you can be certain that it will continue to work in the future purely on the basis of your technical knowledge. If you're relying on a third-party API, you cannot, and that's the distinction that the OP is asking us to take more seriously.
It's like saying MS SQL is political because you have to ask whether or not you want to use it for a political purpose.
The purpose may be political, the tech is not.
The activities associated with the governance of a country
or other area, especially the debate or conflict among
individuals or parties having or hoping to achieve power.
And yes, this can be about power and money, though political decisions come in all sizes.
Political: your opinion, which is biased and mindkilled
Or say I offer a REST API at work to some business functionality locked up in a mainframe in order to expose it for reuse by other apps and workflows, and the consumers desperately want me to do it (or anyone who has the time to do so). What is political about that? Talking about the API is going to revolve around requirements that other apps have that could be satisfied by such an API. How is it useful to view that as a type of political border dispute?
API seems to be a fairly narrow concept to me that appears in various contexts, some of them political and others not.
Google's YouTube APIs played (and still does) a significant part in its turf wars against Microsoft. As did Google's MAPI support, and as did Microsoft's MAPI and SourceSafe APIs in the past (no longer in the MS world, so no idea about TFS).
It's political. It's not "country governance" politics. But it is politics, in the give-and-take-between-opposing-forces sense of e.g. "Your WinPhone users don't get YouTube or Google Calenader because you keep harassing my Android partners".
I agree with Sustrik that it's only considered an API (rather than an internal implementation detail) when multiple parties are negotiating.
I have direct experience doing this sort of thing for years. It's really just a strategy for better leveraging your existing business assets. What is the value of saying, "That's no application programming interface, it's just an implementation detail." I think it just confuses the concept for possible surrounding context. If that context is missing (negotiating, somewhat hostile parties), then all you've done is say that you can't call it API. Hmmm ok then...
Suppose it turns out that your MF RPC (or however your API is implemented) works too slowly, and instead of passing whatever through TCP, you are going to generate a file accessible through the shared MF/non-MF file system with the relevant contents.
If all it takes is calling up Frank in the MF programming department to do the MF side (or even better, doing it yourself) -- then, no, it's not an API any more than your private class names and functions are an API - the MF/non-MF dividing line (which will likely also separate operating systems, programming languages, etc) is of no consequence, because there's no negotiation around changing it.
I have witnessed exactly such a power struggle last time I worked in an environment that had mainframes (some 25 years ago) - functionality that was available on the MF was needed on a unix workstation. The amount of dev work on the unix side to do a mainframe RPC or to do it from scratch was comparable. From most perspectives, the unix re-implementation was a pure win. It sounds like a clear-cut decision, but the MF people argued fiercely against it -- to the best of my understanding, because they were constantly losing turf and relevance. Would you not call this political?
Sure, I get to make all the decisions, but if we now call every decision anyone ever takes political, the term looses all its meaning. Also note that those decisions are not limited to API at all: The implementation is just as political (e.g. availability, performance, privacy).
So it turns out that APIs and protocols (conflated in the article) and the implementation and - if it's a service - any other rule or practise affecting it can have political aspects, just like any other product or service or thing.
Then aswer the second question: Are you getting it? Do people respect you? Or do they ignore your service? Does the lock in happen?
No?
Then there's something wrong with the service. So let's have look at what our users want. Oh, it seems they have agendas of their own. So maybe if we tweaked the API a bit...
But why are you running it? What are your incentives? This is what I was writing about. Programmers, for some unknown reason, try very hard not to express their political interests and try to disguise them using technical lingo.
Maybe I hacked it together on a rainy weekend.
For a few years I was involved in trying to get session-layer security into a networking library.
The disputes were "nominally" technical, in that they were couched in technical language, but there was a strong political dimension. Here were the talking points:
* Knowing that security code is likely to have bugs, isn't it better to do nothing and know it's insecure, instead of doing something, believing it to be secure, and being wrong?
* What cryptographic methods are acceptable? Do we defer to some standards body, like NIST? Or do we reject NIST methods, because they are NSA shills?
* Do we retrofit something off-the-shelf like TLS? (Which implementation?) Or, as a project that defines new protocols, is it within our mandate to innovate on this?
Because there was no consensus on these questions, after several years it's still plaintext-only. There are, however, various "dark forks" that take minority positions, because writing code is easier than convincing people to your side.
Lack of political consensus (on many issues besides this one) is killing the project, to whatever extent it isn't dead already. And even in its death throes there is this desire to pretend there are no political questions.
this is a great insight
But we must recognize that an API is fundamentally a technical construct, so you can't really have an informed political discussion about an API without exploring the technical aspects at the same time. The devil is in the details, as they say, and APIs are nothing but a big pile of details.
And so is international law. But nobody really believes that international law is fundamentally a legal construct.
This piece is, in many senses, another look at the same phenomenon.
Here it is: API is a POLITICAL concept, not a technical one.
It would be better if author provided concrete examples of politics-driven APIs because it seems like some API functions can be a 99% a technical problem rather than a political one.
Certainly some API calls might be trivialized to "just a function" but other API calls have ramifications of burning lots of real cpu, bandwidth, etc to provide them. Whether the company absorbs the expense of providing that API as a cost of doing business or monetizes it by charging users doesn't seem like it's all reducible to "politics".
I think you're missing the point, which is unfortunately a very common problem among programmers. This can lead to bad situations where political decisions are being made de facto, without a real decision-making process.
Unfortunately, there are usually many opinions on which of the various possible solutions should be used to solve some problem. Often this involves trivial choices based on personal preference (e.g. snake_case vs camleCase). Sometimes the choice ends up affecting other important areas, such as your "burning real CPU" example. It may have far more important ramifications, too, about who has the responsibility for the long-term storage of a particular type of data and how that data can be accessed.
"Politics" is simply what we call the process by which we humans come to an agreement on this kind of question. The article's point (which I strongly agree with) is that choosing who has to pay those CPU or bandwidth costs is a political decision. Often, an API could be designed to make either side be the party that has to run their CPU. If you have a strong opinion about which side that should be, good! Engage in the political process and start negotiation.
On the other hand, purely technical decision usually doesn't need an API. The solution is usually obvious. We (hopefully) take the time to write up an API (or specification, or RFC, ...) for the things where there is not a single technical solution.
Well sure, if you put it that way, we could reframe almost anything as political decisions.
"costs" == "politics"
"adding server racks to service the API" == "politics"
etc, etc.
I was reading author's essay while holding a narrower concept of "politics" in my head. I now get your expansive perspective on "politics" and while I understand where you're coming from, that larger framework is not helpful to me.
>"Politics" is simply what we call the process by which we humans come to an agreement on
Sometimes, the API is just "published" with no process for "agreement". It either exists, or it doesn't. It may have come into existence because it was an easy technical solution.
"Everything is political."
That's kind of the point - if there is debate, we use politics (debate, argument, various decision-making methods such as voting) as the means to solve it.
Your potluck example is exactly the point. It is a political decision to have a potluck vs the host providing the food (which can have a variety of consequences in some situations). The very nature of an API is to make that kind of choice.
For instance, at work we're putting an API into our product so that people can develop plugins. Is that political? I guess you could argue that it creates a dynamic of "us" (the developers) and "them" (3rd party developers), but being that this is a corporate entity, that already existed. The only thing the API does is create an explicit agreement of what we will provide and what we won't. I hesitate to say that's political though, because there's realistically no back and forth negotiating or games being played. The API is what it is, and people can take it or leave it. Is that really political? The boundary already existed, the API is just the "formalization" of that.
What's your motivation for people to be able to develop plugins?
These are business decisions and are reducable to financial terms. To say political is to assume that decision makers are not able to make rational decisions based on economic metrics or chose not to analyze decisions on that level.
I know not every decision make by people under various pressures are done with proper diligence/information, but shouldn't we try to frame things as they are?
A "financial decision" is completely political. It's underlined by a view about who should bear costs and who should reap rewards.
Converting to financial terms means that supporting a certain format brings certain costs to the provider and provides certain benefits to the users (which can be charged). How do you decide if it's worth to implement it? Some organizations will maximize revenue, but that's definitively not the only option, and the choice is political.
In the case of web APIs, there is always a determination made as to where the limit of the host's responsibility lies. If the API exposes more functionality, it costs more to implement and maintain, and the responsibility is on the host, not on the client. If an API is shrunk, then the host shifts the responsibility to the client. In many other fields, changes in an API spec might be called a turf war, not separation of concerns.
A personal anecdote: I currently (not for long though) support and extend a large enterprise application that is licensed by my organization, but is hosted at the licensor's data center. For the last decade or so, this application has been extended with in-process plug-ins/modules that use internally exposed Java APIs and have an internally exposed JSP tag library for UI extension. The complexity of the plug-in system, and the incredibly varied effects it has on customer deployments, has become untenable for the licensor (apparently). So as this enterprise software provider transitions their products to a multi-tenant microservices model (as opposed to the current silo'd monolith we have now), the Java APIs will be gradually phased out, in favor of REST services. Of course, this means that clients will be responsible for maintaining their own server for each extension service (as opposed to the "free" in process hosting previously provided) and will also be responsible for their own UI (including accessibility and mobile concerns), even though it can be iframed in the new UI.
Long story short, this has a lot of the extension developers...upset. Basically they've had an entire integration and extension platform that is now being mostly (if slowly) closed off to them to shift several responsibilities across the border between the licensor and licensee. There are (very good) technical justifications for changing the framework this way, but they sit alongside the political and economic justifications.
There's also the time and money aspect to it. The API isn't usually the top priority for most companies, so the API usually ends up somewhere between a crude interface and a mirror image of what's in the packaged product.
In most cases, its definitely a "don't let perfect be the enemy of good enough" situation.
It reminds me (although I can't find any links, not sure how popular it really was) of the movement in the open source world for not needing the "private" keyword in Java if everything's open source anyway. It's a completely misguided fallacy to assume that encapsulation only happens due to politics and proprietary software.
An API definition is just "here's the functionality/interface I decided to expose to the outside world." There are an infinite number of APIs that can be defined, such that when designing one you have to make a lot of arbitrary choices, sometimes "political" ones. Different groups take different approaches here, and respond differently to feedback, but I'm not aware of an endemic over-politicization problem.
This is part of the reason I don't instantly like solutions that expose databases to web front ends... usually the types of permissions typically needed are made excessively hard or impossible... A resource can be owned by one person, viewed by peers, partially readable by others, and manageable by command structure (management). That's just typical.
Beyond this are the differences between users/logins and accounts... too many systems will conflate the two on the backend even though they can be presented as tethered to begin with, the backend should definitely separate the two.
Given, most APIs are political boundaries within an organization... this isn't entirely a bad things. But that is far from the only reason to create/use those boundaries... security and data integrity are two more.
It's good to recognize that API design accommodates both technical and "political" considerations, but to argue that the concept is one or the other is silly to me.
Sure, an engineering team is a part of an organization. And that team may be the only to represent technical factors (affecting complexity management and cost of development & maintenance) on the political/financial/bureaucratic/business front. The influence held by the engineering team is probably determined by the culture within the organization.
APIs of all kinds directly or indirectly are or support a product. Of course technical factors aren't the only ones that influence product development and therefore API design.
If you zoom out far enough, everything can be viewed as a political/business issue. So why all the fuss about it?
Because what you plainly stated is often (usually?) not acknowledged, and pushed back against if pointed out.
That's well said, I'm tired of this too.
Yes, boundaries often coincide with rivers and mountain ridges. But often they do not."
This is geography, i.e. humans in space. Rivers and mountains are topography and geology material.
Politics is just another lens for looking at the world.
Amazon's control of the dominant language to describe infrastructure (its own web services API), for example, gives it a competitive advantage beyond its head start and inertia.
Of course, an unused API is as apolitical as an unused language, and noting that an API is political due to its usage (and is more political the more used it is) may be a useful extension of the idea.
Terminology aside, I think it's reasonable to note that the interface boundaries between software have noticeable non-technical aspects that the interfaces within software do not.