Society for Technical Communication—Israel Chapter

Question: What is the difference between an application programming interface and a software development kit?

Answer: Documentation, mostly.

That's the short answer. For a fuller answer, you need to know what an application programming interface (API) is.

Let's say that "we" develop a piece of software: Microsoft Windows 95, for example, which was the first 32-bit version of Windows. The Win32 API is an interface aimed at programmers who want to build their own applications on top of Windows 95 and its successors.

Here is how an API fits in, filling the gap between "our software" and "their application":

"Their" application developers are users of "our" software. They need a special kind of interface-not just a graphical user interface or a command-line interface. They need an application programmer's interface. Here, for example, are two statements from the Win32 API:

  VOID GetSystemTime(
     LPSYSTEMTIME lpSystemTime );

  BOOL SetSystemTime(
     CONST SYSTEMTIME *lpSystemTime
     );

This fragment of an API allows programmers to use languages such as C, C++, and Java to call two C functions that are included in the Windows operating system. These two functions, GetSystemTime() and SetSystemTime(), can retrieve and change the time of day on the computer's clock.

The statements that you see above are called variously called signatures, prototypes, user interfaces, and calling sequences. In C and C++, prototypes are collected in header files, which are a special kind source file. An API may be made up of dozens, hundreds, or thousands of prototypes.

Header files are often distributed to users of a C or C++ API. Header files can be, therefore, a minimal form of documentation for an API. The developers of the API may even generously add a few cryptic comments to their prototypes:

  VOID GetSystemTime(
     LPSYSTEMTIME lpSystemTime ); // address of system time structure
  BOOL SetSystemTime(
     CONST SYSTEMTIME *lpSystemTime // address of system time to set
     );

This may be enough for an internal API that is only going to be used by programmers in the same company. But if you want to sell the API as a product, you need much more documentation than just a few comments in a header file, or even a few "how-to" notes from the development team.

A software development kit (SDK) is a productized API: an API that you can sell as a separate product or as a part of a larger software product. That means that it must include not just header files (*.h files) and libraries (*.exe and *.dll files), but also:

• A Developer's Guide, containing detailed overview and how-to information.
• A Reference Manual, containing detailed documentation for each function in the API.
• Sample programs, which are concrete examples of how to use the API.

In practice, developers often use the term "API" to refer to a well documented software development kit. (The "Win32 API" is a good example.) But they never use "SDK" to refer to an API with no documentation and no plans to create any.

Documentation is absolutely essential to an SDK. That knowledge should give technical writers considerable bargaining power in their dealings with SDK developers.

For example, I like to recite "No documentation, no SDK" to particularly recalcitrant developers. They know what I mean. It doesn't do me any good, but at least they do know what I mean!