What is API Documentation?

Written by Peter Gruenbaum

API documentation is a fast-growing segment of technical writing. API stands for Application Programming Interface, and it’s the way that software systems communicate with each other. What sets it apart from other types of documentation is that you are writing for an audience of software developers. APIs provide certain functionality, and software developers need to understand how the APIs work in order to build applications that use them.

There are several types of APIs, including programming APIs, web APIs, and hardware APIs. This article will discuss the two most common types, which are programming and web APIs.

Do you need to know how to write code in order to document APIs? There isn’t a simple answer to that question. For some types of APIs, you should know programming fairly well. For other types, it may not be required, but it is often useful.

Programming APIs

A programming API (also called a “client library” or SDK, for Software Development Kit) is a set of software functionality that runs on a device, such as a smartphone, tablet, desktop, or server. For example, a software developer creating an iPhone app would use the iOS SDK. Let’s say that a developer wanted to be able to pop up a window that asked a question and prompted the user to tap “OK” or “Cancel”. API documentation tells the developer what code is required to do that action. It may involve several steps, such as first creating the dialog, then displaying it, and then reacting to the choice that the user made. The developer needs to know how to specify the message, how to specify what buttons to display, and how to find out what button the user tapped.

API documentation writers definitely need to understand some level of programming in order to document programming APIs, but how much you need to know will vary. The documentation for the iOS example I gave above (UIAlertController) requires a great deal of knowledge about iOS programming in order to understand it. However, many programming APIs are a lot simpler, and require only that you have a good understanding of object-oriented programming languages like Java. If you write documentation without having that solid understanding, then you may write something that is not completely accurate, and developers will no longer trust the documentation.

Web APIs

A web API defines the communication between a client device and a server over the web. Web APIs are a relatively new phenomenon in the software industry, but several recent technology trends (mobile devices, the internet of things, and big data) have made them extremely popular. The site ProgrammableWeb contains a directory of publicly-available web APIs, and they analyze the data and look for trends. As you can see in the graph below, the number of these APIs have grown exponentially. And these are just the public APIs — people in the industry say that there are 10 times more web APIs that are available only internally or to partners.

Source: ProgrammableWeb

Source: ProgrammableWeb

 

There is a debate in the API documentation community as to whether writers need to know how to program in order to document web APIs. Understanding programming can give you a good perspective on how web APIs are used. That said, web APIs are not really about programming as much as they are about data. The most important thing you need to understand to document web APIs is how to document structured data, such as XML (eXtensible Markup Language) and JSON (JavaScript Object Notation).

What API Documentation Should Cover

Like any kind of technical writing, API documentation needs to provide both overview material to orient the reader, and reference material to provide specific information on how to accomplish tasks. Here are sections that are common in API documentation:

• Overview — what the API does and why you should use it
• Getting Started — a short series of steps to quickly get to the first use of the API
• Architecture — for programming APIs, how the various pieces fit together
• Authentication — for web APIs, how security is handled
• Tutorials — step-by-step instructions that leads the reader through how to accomplish common tasks
• Reference — detailed information on what each piece of the API does

How to Learn More

Several resources are available to learn more about API documentation. They include:

STC webinars by Sarah Maddox, Ed Marshall, Joe Malin, and others

Workshops by Marshall Documentation Consulting

Online courses by SDK Bridge

 

 

 

The Content Strategy Term of the Week

TLOCS Cover 268px

For 52 weeks The Language of Content Strategy website introduced 52 terms and 52 definitions from 52 experts in the field of content strategy.

The book The Language of Content Strategy contains all 52 of these terms and definitions, along with essays about the importance of each term and a full index. It is part of The Content Wrangler Series of Content Strategy books.

Here are the weekly terms and their definitions.

Wireframe

Information Architecture

Transactional Content Map

Editorial Calendar

Information Visualization

Message Architecture

Augmented Reality

Intelligent Content

Adaptive Content

Content Management System

Document Engineering

Content Engineering

Transclusion

Modular Content

Content Reuse

XML

Structured Content

Single Sourcing

Taxonomy

Content Scorecard

Content Model

Content Flow

Content Type

Content Matrix

Content Analysis

Content Audit

Content Inventory

Requirements Matrix

Content Brief

Personalization

Search Engine Optimization

Metadata

Findability

Content Quality Assurance

Content Optimization

Accessibility

Content Standard

Content Lifecycle

Content Strategy

Content