Writing API Documentation

A new endeavor is writing API documentation. This may sound daunting, but after a short introductory online course I find it to be only moderately challenging. First, what is API? This is an acronym for “Application Programming Interface,” and what an API does is exchange data between a device (like a cell phone or a laptop) and a server. For example we all have apps on our smartphones these days and the display of today’s weather forecast may well be handled by an API, and it might look something like this:

{
"date": "2020-12-04",
"description": "sunny",
"maxTemp": 42,
"minTemp": 28,
"windSpeed": 12,
"danger": false
}

This is an example of a JSON object (there are two types, JSON and XML), or Java Script Object Notation (and XML is the acronym for eXtensible Markup Language). This chunk of data, for what to expect of tomorrow’s weather, is “structured data” that is passed from a source (like the National Weather Service) to recipients like you and me when we want to check on the weather forecast from our cell phone.

The documentation part is what is in high demand these days. Documentation is needed so that software developers who want to create usefull apps can search for and implement thousands upon thousands of existing API’s that currently exist either in public places (like free software projects) and even private places (like within a corporate private network).

So here’s how I would document the example JSON API above:

ElementDescriptionTypeNotes
dateThe date of the forecaststringFormat is YYYY-MM-DD
descriptionThe type of weather expectedstringMay only have these values: “sunny”, “overcast”, “partly cloudy”, “raining”, and “snowing”
maxTempMaximum temperature on forecast datenumberin degrees Celsius
minTempMinimum temperature on forecast datenumberin degrees Celsius
windSpeedWind velocitynumberin km per hour, kph
dangerFlag if conditions are expected to be dangerousbooleanTrue if conditions are expected to be dangerous, otherwise false
### A response for a one-day weather forecast

Leave a Reply

Your email address will not be published. Required fields are marked *