Technical Writing ToolBox

A Blog on Technical Writing

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 televi...

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 = ShutDOwn
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.

Have you ever created API documentation? Do you find it interesting? Leave a comment and let me know.


18 responses to “What is API documentation?

  1. Tarun April 17, 2012 at 12:52 am

    Very good article. Excellent description.

  2. Gurudeep May 25, 2012 at 7:44 am

    Can you please share the content on API documentation? or if possible, share API documents or useful links to the documentation so that it will be a learning experience for me.

    • Kirti A. June 1, 2012 at 5:08 am

      Very nice post on API documentation. If am interested to learn API documentation technique. Could you please share any book/blog/ website which explains in detail how API documentation is done.

    • rahul August 1, 2014 at 9:38 am

      Are you still working in Canada. Well, most are Web API’s available on net. Here is a sample:

      I was working with GroupDocs for a year. They use Swagger to publish API docs. This is a buzz word in tech comm.

  3. mind December 19, 2012 at 1:43 am

    Hello, after reading this remarkable post i am too delighted to share my know-how here with mates.

  4. Kiran February 19, 2014 at 3:44 am

    Hi Gurpreet,

    Your article helps in understanding API.
    I have never written an API document so far, but in my current organization i have to write an API document.

    Can you please guide me how to get started with the API documenation?

    Kiran Lokhande

  5. Bonnie March 23, 2014 at 10:41 pm

    Hey I know this is off topic but I was wondering if you knew of any widgets I could add to my blog
    that automatically tweet my newest twitter updates.
    I’ve been looking for a plug-in like this for quite some time and was hoping maybe
    you would have some experience with something like this.

    Please let me know if you run into anything. I truly enjoy reading your blog and I look forward to
    your new updates.

  6. Roy Aki March 26, 2014 at 8:27 pm

    You could definitely see your enthusiasm within the work
    you write. The sector hopes for even more passionate writers
    such as you who are not afraid to mention how they believe.
    At all times follow your heart.

  7. April 2, 2014 at 3:00 am

    I take pleasure in, lead to I found exactly what I was looking for.

    You’ve ended my four day long hunt! God Bless you man.

    Have a great day. Bye

  8. Nitin September 23, 2014 at 2:25 am

    Informative article with very clear explanation .

  9. Stop Pedaling September 30, 2014 at 10:34 pm

    First off I want to say terrific blog! I haad a quick question whicch I’d
    like to assk if you don’t mind. I was interested to find out
    how you center yourself and clear your mind beffore writing.

    I have had a tough time clearing my thoughts in getting my thoughts out.
    I truly do taake pleasure in writing but it just
    seems like the first 10 too 15 minutes are usually wasted simply just trying to
    figure out how to begin. Any suggestions or tips? Cheers!

  10. Pingback: jQuery queries? | nouranwebmedia2

  11. Jyotika Rajput Mehra February 18, 2016 at 6:39 pm

    Thank you for sharing this article. Too useful. 🙂

  12. Pingback: Understanding of Web Service & REST API | OptimumBrew Technology Pvt. Ltd.

  13. Kat Leffler December 28, 2016 at 12:13 pm

    I am currently updating a web API document for a SaaS product. It’s big! 300+ pages with a SOAP discussion and a few message stack diagrams. I am looking for information on two things:
    1. Working with the images to convert them into an editable form.
    2. Conversion of the whole document into HTML format.
    Any ideas?

  14. Pingback: Technical writing - what is it and where can I find it?

  15. Pingback: Free Software for Documenting Your C# API Code | Jim's Adventures in Programming

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: