
Let's stop kidding ourselves about APIs - JoshTriplett
http://250bpm.com/blog:55#
======
rjknight
I'm puzzled by the pushback this is getting. There are many questions about
APIs which are purely technical:

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'.

~~~
delluminatus
Even many of your examples of "technical" questions seem at least partly
political to me (which just reinforces your point, I think). For example:

* 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.

~~~
rjknight
I agree, although I think that some of those are less critical issues. For me,
the reason to be aware of the politics around APIs is that APIs - unlike
libraries - imply an ongoing relationship.

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.

------
quonn
This article is very confused. It makes a case that an API is a boundary
(which it is) and because there are also other boundaries (like borders) it
must be a political boundary (which it is not). But it doesn't stop there.
Once it has mistakenly _added_ the attribute "political" to boundary it goes
on to essentially _drop_ "boundary", too. So now we are left with "political",
so APIs must be about "power, money and respect" after all. Well, that's not
my experience and this text does not provide a reasonable argument for this
extraordinary claim. However I applaud the author for having tried to
formulate a new concept that could have been interesting.

~~~
erikpukinskis
I was excited to see a contrarian perspective here, but I'm disappointed that
you've just selectively quoted the parent while claiming they are wrong. I
would love to know how you define political and why you think the decision to
make a function public instead of private is apolitical.

~~~
quonn
It's not apolitical. But it's also not necessarily political. Sure there can
be different opinions about an API and some of those might have a political
motivation (for a very broad definition of the word political). But this does
not mean that APIs are primarily about politics. And there is certainly a huge
leap to such concepts like power and money.

~~~
pdkl95
[http://www.oxforddictionaries.com/us/definition/american_eng...](http://www.oxforddictionaries.com/us/definition/american_english/politics)

    
    
        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.
    

Politics is not just about nation-states and the type of work usually
associated with governments. Politics is what we call the various ways we
humans solve our disagreements.

And yes, this can be about power and money, though political decisions come in
all sizes.

------
drewcrawford
Comments here are a dearth of actual examples. You can argue APIs are a
Broadway musical if you don't give any clue what kind of APIs you're talking
about.

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.

~~~
jonahx
> because writing code is easier than convincing people to your side.

this is a great insight

------
dasil003
The author makes a good point which is that engineers have a tendency to couch
emotional and political rationalizations in technical terms and then
annoyingly believe that their objectivity is unassailable. That's definitely a
thing.

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.

~~~
rumcajz
> ... 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.

~~~
dasil003
Nobody believes that law [...] is a legal construct?

~~~
rumcajz
Let's take Treaty of Versailles, for example. Who would you say was
responsible for it? Lawyers or politicians?

------
beagle3
Don't remember the name of this adage, but there's one that says "The
structure of a project tends to reflect the structure of the organization
responsible for it" \- e.g. software modules tend to reflect organizational
structure much more closely than they reflect separation of concerns (though,
of course, the organizational structure itself reflects a separation of
concerns). In my experience, that is definitely true.

This piece is, in many senses, another look at the same phenomenon.

~~~
rumcajz
It's called Conway's law.

------
jasode
_> 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._

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".

~~~
pdkl95
Examples? Try "every API ever created".

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.

~~~
jasode
_> choosing who has to pay those CPU or bandwidth costs is a political
decision. _

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.
    

Should a coupling hosting a party at home ask their guests to bring potluck?
Structuring the cost of food and deciding whether it's the host or the guests
funding it is ultimately a "political decision".

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.

~~~
rumcajz
The term "politics" is not as all-covering as it may seem at first. It refers
to the process of people and human groups reconciling conflicting interests.

------
JoshTriplett
Many people commenting here are talking about the use of the term "political".
Another way to look at it: APIs are fundamentally a _social_ or _community_
thing, more so than a technical thing. "politics" applies here more in the
sense of "interpersonal politics" often used to describe any non-purely-
technical social process.

------
overgard
I agree that an API is a boundary, and that boundaries can be political, but
the boundary = politics argument seems like it dilutes what it means to be
political. In a way, you can describe almost any person-to-person interaction
as political (there are always subtleties and unspoken motives), but I'm not
sure that's useful. To me politics specifically suggests covert social games
under the cover of more formal interactions. Most API's though, I think, exist
for pretty straightforward reasons. Yeah it's a boundary between groups, but
that doesn't mean much more than that, boundaries make a lot of logistical
sense.

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.

~~~
icebraining
_For instance, at work we 're putting an API into our product so that people
can develop plugins. Is that political?_

What's your motivation for people to be able to develop plugins?

------
reilly3000
I think it is precarious to call these political decisions rather than
business decisions. If I'm deciding to return despises as JSON, XML, or both I
am making a decision about: 1\. Cost to maintain one or two formats 2\. Cost
to develop one or two formats 3\. Benefit of having multiple formats And some
subsidiary questions like: 1\. What tooling is availabile for the formats? 2\.
What will make my customers/consumers happiest? 3\. Will this have impact on
how many integrations with my service get built?

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?

~~~
icebraining
This is when you know a political view is really embedded in a society: when
decisions made under it are assumed to be apolitical.

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.

------
dikaiosune
I was going to reply to another comment, but then my response became much more
general. So this is more of a general response to those comments that disagree
with the original article.

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.

------
brianmcconnell
Among other things I am responsible for my employer's REST API. I don't really
see where an API is inherently political. It could be, if you're trying to get
lots of different organizations to buy into it as a quasi standard (OAuth?),
but most APIs I encounter simply provide a decent separation of concerns so
external users can do what they need to do without knowing what's happening on
the other side.

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.

------
ninkendo
Breaking things out into APIs is one way of adhering to the Single
Responsibility Principle, which has nothing to do with politics.
(Microservices are a good example of this, but so are basic things about
software design like encapsulation.) I think the author's assertion is overly
broad.

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.

------
resu_nimda
I don't understand. What is the problem and what is the proposed solution?

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.

------
tracker1
I both agree and disagree... in the case of software, in general you usually
want two boundaries, regardless of if you are the only one generating them...
between your front end and your data... usually front to back, and back to
database.

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.

------
ademarre
Okay. Technical considerations aren't the only things that matter. Correct.

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?

~~~
icebraining
_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.

------
pbreit
I'd like to see more follow what Balanced Payments did: use it's public facing
APIs to power its dashboard. Not only that, it open sourced the dashboard.

[https://github.com/balanced/balanced-
dashboard](https://github.com/balanced/balanced-dashboard)

------
serve_yay
> 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.

That's well said, I'm tired of this too.

------
golergka
Another good way of thinking about API is a user interface. And by the way,
yes, when your "helper function" is exposed publicly to the whole project, and
every developer ended up using it in 10 different places, you can safely
consider this function to be an API.

------
fapjacks
This is kind of ridiculous because politics is simply the interface (i.e.
relationship) between two or more people/groups/entities/whatever. It is
stating the obvious as though it were revolutionary: "Rain is simply water
falling from the sky!! Wake _up_ people!" _Of course_ APIs are a kind of
political boundary. Why is this some kind of genius revelation?

------
erispoe
"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."

This is geography, i.e. humans in space. Rivers and mountains are topography
and geology material.

------
morgante
Yes, APIs are political. Just like everything else.

Politics is just another lens for looking at the world.

------
duggan
I'd never really considered it before, but of course the author is correct.
Control of an API is the control of a language, and as with 1984's Newspeak,
control of language is a powerful tool.

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.

~~~
JoshTriplett
See also "Code and other laws of cyberspace"; APIs are part of that. They say
how other programs can and cannot interact with yours.

------
chipsy
Of course I disagree with the article. APIs are not the political problem,
technology is. It's inherent in saying that you're going to "change the
world," be "disruptive" or "revolutionary." When software dies, it goes
unmaintained and unused in favor of something more popular. These are
qualities of political platforms. The word "platform" is used in technology in
a remarkably similar way. So it's not an API thing.

~~~
JoshTriplett
Then it should be a logical extension that APIs are analogous to the
relationships between political platforms, which is the premise of the
article. Along similar lines, consider that people talk about APIs as
"contracts". More generally, the article makes the point that APIs are more
social than technical.

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.

