What is API documentation?

API documentation, also known as Programmers documentation, is a deliverable of technical writing in which a technical writer develops instructions about how to effectively use a software API, hardware (SCPIs) or web-API.

What is an API?

API is an acronym which stands for Application Programming Interface. An API is a set of predefined rules and specifications that a software program can follow to use the services and resources provided by another software program. In other words, API is a kind of communication channel through which two separate programs can communicate with each other and share each others service and resources.

A typical firmware-controlled device, a television remote control. Consumer products like this have been using firmware since the 1970s. (Photo credit: Wikipedia)

For example, take the example of a TV. You have a hardware button on your TV which turns it ON/OFF. Now let’s say you want to turn ON the TV from a distance. You just press the ON/OFF button on a remote control and the TV set mimics the command given by the remote control. This is how API works! Think of TV as a Software Program having services and resources, and the TV Remote control as another software program which use these resources. The method (or radio/infrared waves) through which a remote control communicates with a TV set is an API.

Types of API?

APIs can be created for a broad set of software programs such as Operating Systems (OS is a big program, right?), software applications, programmable hardware and software libraries so that other software programs can use the services (if any) provided by these programs.

Depending upon the medium and services it provides, APIs can be divided into three distinct groups:

• Software API
• SCPI (Hardware API)
• WebAPI

Software API are APIs that provide access to the functions or services provided by another software.

For example, Microsoft Windows has a number of APIs available in its Shell32 library. One of the commonly used API is SHExitWindowsEx which can be used by a software program to log off, shutdown, restart, forced shutdown or power off the Windows operating system.

The syntax call is:

SHExitWindowsEx n (where n can take values of 0,1,2,4 and 8)

0 = Log Off

1 = Shut down

2 = Restart

4 = Forced

8 = Poweroff

SCPI is an acronym which stands for Standard Commands for Programmable Instruments. SCPI (commonly pronounced as ‘skippy’) is a set of predefined rules and specifications which is used for controlling programmable test and measurement devices. What API is for a software program, SCPI is for a programmable test and measurement devices.

For example, “*IDN?” is a standard SCPI command used in many interfaces (GPIB) and programmable instruments to fetch basic identification data from a device.

WebAPI are APIs that provide access to the functions or services provided by a web-service (or a website). In its simplest form, a WebApi is typically a defined set of Hypertext Transfer Protocol (HTTP) request messages,which may contain a definition of the structure of response message as well. The response of a WebAPI is usually written in a Markup language such as Extensible Markup Language (XML) or JavaScript Object Notation (JSON) format.

What is API Documentation?

API documentation is a deliverable of a technical writer which describes, with examples, how to effectively use a Software, Hardware or Web API. It requires a thorough understanding of the API, its arguments, its return type and the languages and interface it supports. Technical Writer having programming knowledge often create instructions, procedures and example for APIs that ships along with a software product.