API, Software Development, Technical Writing
How To Write Technical Documentation For APIs
One of the threads on LinkedIn is how to write technical documentation for APIs. It’s been many years since I’ve documented an API (Java & Oracle) so if you have any thoughts on the best way to do this, then please jump in.
An application programming interface (API) is an interface implemented by a software program to enable interaction with other software, much in the same way that a user interface facilitates interaction between humans and computers.
What is an API?
APIs are implemented by applications, libraries and operating systems to determine the vocabulary and calling conventions the programmer should employ to use their services. It may include specifications for routines, data structures, object classes and protocols used to communicate between the consumer and implementer of the API. Wikipedia
Concept
An API is an abstraction that defines and describes an interface for the interaction with a set of functions used by components of a software system. The software that provides the functions described by an API is said to be an implementation of the API.
An API can be:
Generic — the full set of API that are bundled in the libraries of a programming language (e.g. the standard Template Library in C++ or the Java API)- Specific — meant to address a specific problem, like the Google MAPs API or the Java API for XML Web Services.
- Language-dependent — available only in a given programming language. It is only available by using the syntax and elements of that language to make the API convenient to use in this context.
- Language-independent — written in a way that means it can be called from several programming languages. This is a desired feature for a service-oriented API that is not bound to a specific process or system and may be provided as remote procedure calls or web services.
For example, a website that allows users to review local restaurants is able to layer their reviews over maps taken from Google Maps, because Google Maps has an API that allows it. Google Maps’ API controls what information a third-party site can grab, and what can be done with it.
“API” may be used to refer to a complete interface, a single function, or even a set of multiple APIs provided by an organization. Thus, the scope of meaning is usually determined by the person or document that communicates the information.
API Guidelines
Here are some sites that offer guidelines and examples of API documentation.
- API Writing – http://api-writing.blogspot.com/
- Dustin Diaz, API Writing Tips – http://www.dustindiaz.com/api-writing-tips/
- Rajeev Jain, Developing your First API Guide – http://www.stc-india.org/conferences/2006/agenda_web.htm
- Sun API Documentation – http://java.sun.com/j2se/1.4.2/docs/api/
- API Documentation Trends and Opportunities – http://www.stc-india.org/conferences/2004/PprPrest/Conf_Rajeev.htm
- Susan W Gallagher, What are APIs and SDKs – http://members.cox.net/susanwg/susanwg/api.html
- Generating API documentation in HTML format – http://java.sun.com/j2se/javadoc/index.jsp
Twitter’s API Documentation
Twitter has done a great job documenting its API and breaks out all the different component.
“The Twitter API consists of three parts: two REST APIs and a Streaming API. The two distinct REST APIs are entirely due to history. Summize, Inc. was originally an independent company that provided search capability for Twitter data. The Streaming API is distinct from the two REST APIs as Streaming supports long-lived connections on a different architecture.” http://apiwiki.twitter.com
Tips for writing API documentation
What advice would you give to someone writing their first API document set? What mistakes do technical writers make when approaching this area?
FYI: Twitter API: Up and Running: Learn How to Build Applications with the Twitter API
