An API is not a thing, it is a weird presence we communicate with, develop and implement. An API is an abstract idea, one that is hard to catch for non-developers.
I find some concepts challenging to truly understand, let alone explain without context. Take language or loyalty for example. Or an API. What is it? Like Schrödinger’s cat, such abstract concepts loose their real characteristics if we try to pin a static definition on them. But if a feline entity is so useful in explaining the quantum state, maybe metaphors would work for APIs too. I studied quantum chemistry, so you see how the cat got here. In this blogpost, I try to show what an API is in action, using metaphors from different professions and calling on definitions I found on the internet. This one goes out for the lawyer, the med, the interpreter and the writer.
Machine-to-machine
An Application Programming Interface or API enables, controls, simplifies and stabilizes data exchange between software without human interaction. It isn’t executable, it’s not code, and you won’t see it written out from beginning to end. Its name defines it as an interface, but not one for humans. It facilitates software-to-software communication.
What would this be if it were for human-to-human communication?
The interpreter: Enable
“Programming Interfaces enable software to interact with other software through exposed functionality.”1
An API is an enabling interpreter:
“Data can be consumed or distributed using an API (or interpreter) so that two different kinds of software can communicate. Good software has a strong translator (API) that follows rules and protocols for security and data cleanliness.”2
“In the simplest terms, APIs are sets of requirements that govern how one application can talk to another.”3
The lawyer: Control
A Stack Exchange answer that helped me best with perspective defines APIs as a contract:
“1) What is an API?
API is a contract. A promise to perform described services when asked in specific ways.
2) How is it used?
According to the rules specified in the contract. The whole point of an API is to define how it’s used.
3) When and where is it used?
It’s used when 2 or more separate systems need to work together to achieve something they can’t do alone.”4
We must leave legal feathers unruffled, software licensing can get problematic if too much is exposed, even in open source. An API is like a firewall: it gives controlled access rather than full unlimited access.
The writer: Simplify
According to wiki, an API is “a particular set of rules (‘code’) and specifications that software programs can follow to communicate with each other”5
These rules and specifications are published in the reference docs: the particular set of functions and their parameters (endpoints) which will follow a standardized behavior. This standardization is key in reading and connecting the millions of custom software and creating the end user’s flow-like experience.
The med: Stabilize
An API is a digital semipermeable membrane. We need not know all that is there, constantly changing in the API provider’s code or database in order to get our specific questions answered. We only need to know how to formulate our questions to get them processed and then how to interpret the response messages. Our interaction via this membrane is stable. Until a metamorphosis, that is.
An example
We want answers from a database. We can get the full specs and full/role-restricted access to the database and query it directly. But this is
- too much work,
- often not an acceptable option for the owner of the database (eg. for banks) and
- the database might be changing too fast.
Reaching out to the database via its API simplifies our job: we don’t need to know the database-schema. Stability is ensured because we don’t have to follow up its changes either, we only have to ask the potential predefined questions and we will receive the answers. API-enabled transactions with the database are stable and most importantly, fast: once set up, no human mediation is required.
This stability and speed, plus the controlled access is what “allows organizations to expose defined assets, data, or services for public consumption. That makes it possible for applications to share data and take actions on one another’s behalf without requiring developers to give full access. 6
At Pronovix we build systems to document APIs that aggregate docs from different sources. To find out about our Dev Portal work, check out our landing page, or if you would like to build an API for your docs, read our series on Artificial Intelligence and documentation.
Special thanks to my colleagues Steve and Kristof and to Erik Romijn for talking this article through with me.
Cover image CC by Freemesm
