What is API Documentation

Developers need to work with third party code to develop complete applications. In order to integrate the applications with third party code programmers need well written API documentation. API stands for Application Programming Interface. API Documents are also required to work on platforms (and develop applications) such as Intuit, Sun, Google and Salesforce.com.

API documentation requires writing about programming code. It’s an advantage to have a technical background to write API documents. Since it is difficult for the companies to find writers with technical background, non-technical writers are writing API documents. Technical writers, with non-technical background, find the word ‘API Documentation’ a bit too technical, and generally cause anxiety in them. My aim is to help reduce some of this anxiety by making them more aware of what ‘API documentation is all about.

API Documentation – Software Development Kit (SDK) and Programmer’s Documentation

Before we start talking about the API documentation, let’s see the bigger picture first, wherein the requirement for a developer to work with the company’s code requires more than API documentation. Programmers may need:

  • APIs
  • Code Libraries
  • Tutorials
  • Sample Programs

Programmer’s documentation describes all or some of above mentioned points. Organizations include all of these in SDK (Software Development Kit).

Types of Programmer’s Documentation

Programmer’s documentation may have some or all of the following:

  • API reference documents
  • Configuration and Installation guide
  • Programmer’s guide

Here we are focusing on the first point. API reference documentation and also be referred as API documentation, and these terms will be interchangeably used.

Overview of API documentation

API documentation is the most commonly used programmer’s documentation. It is basically a reference documents which describes:

  • A Software’s code
  • The parameters a programmer sends (or the request sent) to the software.
  • What the software does
  • Response from the software

API documentation includes information about the code. It gives details about the APIs (also called methods and functions) that developers use to connect or interface with the software application. API documentation can be done for all sorts of software technologies such as Java, JavaScript, C++/C#, TCP/IP, AJAX, JSP tag libraries, and XML schemas.

Key areas to be considered when writing API document are:

  • Content Source
  • Document plan or sketch
  • Delivery layout
  • Information required for each function in the document
  • Automatic document creation programs

Source for Creating API Documentation

Information for API documentation comes from one of the following source:

  • Requirement or Specifications
  • Source code
  • By using the application
  • Raw APIs written by the developers or QA or other technical group
  • Documents for previous release
  • Bug trackers e.g. Bugzilla

Standard groups Writers often start out with the raw content provided by the programmers.

Typical Outline of an API Document

Most of the information in the API reference documents is targeted towards the APIs themselves. There is nothing like a “standalone outline” – but an API document will consist of the following:

  • Introduction: Brief about what the API can do
  • Quick Tutorial: How to get started quickly by taking a few simple examples.
  • Concepts: Important concepts to know before using the API
  • Reference: This portion constitutes more than 80 percent of the content. Contains list of all functions along with the detailed information for each one

How to Document each Function in an API Document

The exact content may differ for each document, but following should be included for each function:

  • Description: A small description about what a function does.
  • Syntax: The syntax about the parameter of the code, the sequence in which they occur, required and optional elements, etc.
  • Parameters: The parameters of the function. Arguments and Return type can be written separately also.
  • Error Messages: Syntax of error messages.
  • Example Code: Small snippet of code
  • Related Links: Other functions that are related

Example of an API Document

The following example shows how a typical function is documented. More than 80 percent content of an API document will look similar to what you see below.

ArrayBI→ collect()

Description

collect() calls a test function for each element in the array. All elements for

which the function returns a non-zero value are collected in a new array which

is returned.

Syntax

ArrayBI ArrayBI→ collect( AlFunction testFunc, … );

Returns

An array containing those elements for which testFunc returned a non-zero value.

Arguments

testFunc:

A function that should accept only one item from the array as its first argument. A value of non-zero is returned if the item is collected; a value of zero if the item is not collected. Additional arguments can be supplied and are passed to the test function after an ArrayBI item. The test function should be prepared to accept these additional arguments.

Example

Continuing from the example for accumulate(), the following code returns all the odd values in arr:

arr->collect( func(x) {

return (x%2) != 0; } ); // Returns (5 9)

See Also

  • AlArray
  • List of Classes

API Documentation Tools

API documents can be extremely long and repetitive. But API Documentation tools can really prove to be helpful. Developers insert comments to the application during development process. The API Documentation tools then parse or break down the code for inserted comments to make API documents. This works better when programmers and writers agree upon the type of comments to be inserted. Some popular API documentation tools include:

  • JavaDoc(For Java Code)
  • Doxygen(For .NET Code)

Although the tools help generate quickly, but can only work if there is good discipline of writing good comments in agreed upon formats. This may also need special training of the programmers who generally shy away from writing comments.

Common delivery formats for API Documents

Once the documentation is complete it is delivered as a PDF or as online help or both. The idea is to deliver it in a printable format.

The concentration is more on online help as organizations are moving towards SaaS (Software as a Service) model. Help can be generated in any style or format, depending on the software help, e.g. WebHelp, HtmlHelp and JavaHelp etc. WebHelp is gaining popularity as organizations are making web-based delivery models.

Conclusion

Although API documentation is a bit technical in nature, with patience, even technical writers with non-technical background can also start writing these API documents.