What is API documentation?
In this post I’m going to clear up some of the haze around software documentation for someone who’s interested but has no software background.
First, define an API. An Application Programming Interface (API) is a generic term for “toolbox.” It’s the contractual lingo that makes machines understand each other. The tools are for teachers: teachers who tell the machine how to do stuff. That’s the data entry guy. Sometimes, they’re called programmers or developers. Sometimes, they evolve into software engineers and data scientists.
At a most basic level, a program is a set of instructions that takes an input and produces an output. When you encounter an API, all you have to do is follow the instructions and feed the correct inputs, and you will get an output. The same question pops up over and over: “What am I allowed to input, and what are the expected outputs?”
An API is the crystalization of a developer’s opinion. Excel spreadsheets are an API. Someone, somewhere, determined that you if you want to select a bunch of cells, you should write A2:B6 because that’s how we label cells on a chess board. They coded it into Excel and told the end-users, “This is how you do it.”
The instructions for most tools are generally non-existent. If you show a kid your toolbox, and they’ve never seen a hammer or a wrench before, do you expect them to know what to do? Yet all across the software industry, this is how people are operating.
I still don’t understand APIs! #
Let’s take a simple math equation that you learn in algebra:
Equation to find a combined age.
x + y = Z
where x is the age of Person A,
y is the age of the Person B,
Z is the combined ages of Person A and Person B.
If you can understand the above example, congrats! You’ve just understood an API.
Is it really that simple? #
Like most things, the simpler it looks, the more complexity it hides.
Back to algebra class. Let’s consider that
x + y = Z
can also be written in function notation:
f(x, y) = x + y
where f denotes some function.
Conveniently, this is similar to how functions, sometimes known as methods*, are defined in most programming languages. They use curly brackets so the computer knows when the declaration starts and ends:
f(x, y) {x + y}
What is “f”? It can be anything. Leave it as is, and the computer will happily do its job.
But we are humans, not robots! Ask someone to compute f from x and y. They will ask you, “Why should I do this?” and if you can’t give them a good reason, they’ll ignore your tool.
In this case, we can rename the function to addNumbers(x, y). Hmm, still too vague. How about we define the parameters too? addAges(ageOfX, ageOfY).
Jargon time
Parameters are synonymous with arguments, in the philosophical sense.
Even after functions have been given a name, there’s still many questions. Why are we adding the ages? To what end does this achieve?
Well, addAges(x, y) calculates the sum of ages. Using that info, another function averageAges(x, y, z, .... a) will calculate the average age. Finally, the application will use this info to calculate population demographics. Aha, there’s the big reason.
*Some people are pedantic about the difference between a function and a method. A method is a function which belongs to a certain Class. A Class is an arbitrary category that someone thinks should be a category.
For example,Farmingmethods are distinct fromGardeningmethods, but they both might use thedigWithShovelfunction.
Network effects #
Algorithms are complicated. Programs go beyond a single computer and communicate with multiple computers, and this frenzy of network activity is called “the cloud.” There are laws for our Internet highways, known as protocols. Just like how roads and cars must be built according to a minimum standard, network APIs are built according to best practices. Currently, the most widespread standard is REpresentational State Transfer (REST), and REST APIs are conformant to those expectations.
You may have a function like getAverageAge(country). TCP/IP protocol uses a different syntax than our traditional algebraic functions.
- Average age of which country?
country=Guatemala - Which server am I supposed to fetch that kind of data from?
api.cooldata.com - How do I transfer this data securely?
httpsprotocol - What happens if I download too much from your server?
Don't worry, we've implemented checks to prevent congestion and will send you an error code 429 when you hit your rate limits.
This is the query that addresses the above points:
GET https://api.cooldata.com/averageAge?country=GuatemalaExpected response: the average age of Guatemala, otherwise 429 if you spam us too much
What if I want to edit your data? You’re not supposed to, but you can submit to /addCitizen:
POST https://api.cooldata.com/addCitizen?country=GuatemalaSend a JSON into the Body of the “envelope:”
{
"name": "Bobbito",
"birthday": "1987-03-51"
}
⛔ Wait a minute, 51 is not a valid date. You’ll be getting a code of 400: Bad syntax.
🆗 If we’ve successfully received your submission, we’ll let you know with a 200: OK
What do browser codes mean?
Codes can be anything the developer wants them to be, but we as a community have decided that’s too confusing. Mozilla has a list of conventions that developers are supposed to follow.
Nothing is standard until you write it #
There are an infinite amount of algorithms, an infinite amount of APIs. How do you write guidelines for making the most out of them?
Good API documentation describes the purpose of a program and how to use it, convinces you to adopt it, and provides a way to give feedback. This is very much in line with Aristotle’s Modes of Persuasion: kairos, pathos, logos, ethos (context, emotion, reason, credibility).
In the end, an API is an opinion on how something should be done. Some opinions are worth considering, and some aren’t. If the docs are outdated, unappealing, disorganized, or untrustworthy, who would want to use that API?
What does good API documentation look like? #
One of my favorites for REST APIs is Clearbit docs. The structure is direct and straightforward, and the dscriptions are human-crafted.
They provide 3 SDKs in different languages (Ruby, Node.js, Python) and have examples for each, although those code samples tend to be auto-generated and not necessary for all APIs.
The tables are clean and 2-columns only, reflecting the simple nature of JSON as a key-value pair (unlike some monstrocities that span the horizontal width and have 3+ columns).
Finally, the whole document is a single, flat page. It’s easy to Ctrl + F and search for terms. Flat, meaning no collapsed menus, sometimes called accordions. Honestly, they are accessibility headaches.
Who writes API Documentation? #
This is a question of much debate. The only answer that makes sense is, “Anyone who understands what the API achieves.” This could mean the engineer who designed it, the developer who wrote unit tests and has plenty of examples, or the writer who knows how to explain with clarity.
Every engineer is knee-deep in the implementation of their algorithms. Sometimes they’re excited and give you a personal tour of the plumbing. Sometimes they hate their job and will talk in circles, skirting the details.
Documentation is a multi-step research process which takes anthropological pluckiness moreso than math knowledge.
The QA tester says, “Well, I expected the fruit juicer to dispense juice when I flip the switch, but it went off the rails and threw an orange at me.”
The engineer says, “The machine is actully a fruit washer. If you twist the lid tight enough, and oranges are loaded properly, it’ll clean the fruit for you.”
“Oh.”
“Only water is allowed in the resevoir. The scrubbers get too sticky if you don’t clean them enough. Did you know there’s a little hatch under the dial?”
If you’re assigned to write the docs, you’re the marriage counselor between the input and the output. You’re not here to tell someone how to design an algorithm, but you’re here to point out that some of the expectations are a little wonky, and the labels on the machine aren’t clear, and there’s some potentially dangerous cheats. A neutral 3rd party will be able to identify discrepencies and set the terms for mutual understanding.
How do I learn API documentation? #
It will take some time to get used to the jargon. The concept of headers and bodies (sometimes called payloads) are familiar if you’ve ever written a letter and mailed it in an envelope. However, they are meant to address a computer instead of a human.
Besides the usual I’d Rather Be Writing: API doc course, here are other ideas:
- Press F12 Chrome or Edge browser to open the Dev Console. Go to the Network tab and browse a social media site like Instagram. Take a look at what gets returned and see if you recognize anything.
- Install WordPress on your computer and call APIs from your localhost.
- Get RapiDoc running with the sample petstore OpenAPI.
- Find a project on GitHub, GitLab, or CodeBerg with an OpenAPI schema that isn’t well documented. Compare them to docs from Google, Microsoft, or any technology company.
Image by capn-damo