This article is published at https://www.dyingtowrite.com/posts/2021/34_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, we must 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. There needs to be a person to teach the machine how to do stuff, and 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. An API is the crystalization of a developer's opinion. 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?"
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. Then, 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.
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.
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, Farming methods are distinct from Gardening methods, but they both might use the
digWithShovelfunction.
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.
country=Guatemalaapi.cooldata.comhttps protocolDon'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:
https://api.cooldata.com/averageAge?country=GuatemalaExpected response: the average age of Guatemala, otherwise 429 if you spam us too much
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.
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?
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 concerned about 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.