Features

Introduction to Documenting: APIs, SDKs, and Web Services

December 20, 2012

By Gwendolynne Barr | Member

What is an API? What does it mean to document an API? And how can you get into this niche if you don’t have a computer science degree? To investigate these questions, I interviewed four technical writers who specialize in documenting APIs and API-related products such as Web services and software development kits (SDKs).

I also spoke with Charles Hoffman, Sunil Vemulapalli, and Alan Michels, who reviewed my article and gave me advice. I am grateful to all of them for patiently explaining the world of APIs and what their documentation is all about.

APIs on the Rise

An API (Application Programming Interface) is the means by which two software systems talk to each other. A Web service is a type of API often called a Web API. And an SDK (software development kit) is a set of tools that include the API to assist the application developer in using the API.

These days, offering an API to the public is all the rage. Twitter does it (https://dev.twitter.com/docs), Facebook does it (http://developers.facebook.com/), even BART does it (www.bart.gov/schedules/developers/). The question is, what are APIs, exactly, and why are so many companies creating them? In February, the Programmable Web blog counted 5,000 APIs (there are now over 8,000)and noted that “like the Wild West, there’s an ‘anything goes’ approach” to API development (http://blog.programmableweb.com/2012/02/06/5000-apis-facebook-google-and-twitter-are-changing-the-web/).

Back in 1999, Susan Gallagher wrote that encapsulation and modularity, principles of object-oriented programming (OOP), “are the forces that drive the development of APIs and SDKs.” Encapsulation allows for code to be hidden behind an interface; modularity allows for it to be arranged in classes hierarchically and easily packaged.

In other words, APIs let a company share the power of its software implementation without revealing the code itself. Enterprising developers use these APIs to create applications or “apps” that leverage the functionality of those implementations.

But encapsulation and modularity have been around for a long time. Why the sudden increase in APIs? Richard Smith thinks one reason is “the sharing of services between organizations.” Everyone benefits when services are shared: application developers gain access to a commercial service, end users have a tightly integrated app, and both companies—the one offering the API and the one using it—make money.

Definitions

Before we look at what the job of API documentation entails, let us clarify the terms.

What is an API?

An Application Programming Interface, or API, defines how one software component can communicate with another. “It’s a hook,” said Richard Smith, “that gives you access to someone’s software library.” That hook—that interface for programming applications—can be a set of methods that you call to access the functionality of a program.

More simply, when you physically click a button in Google Maps, you are “calling” some method in their code. Methods in computer code are like verbs in a human language. They define the actions of a program. The code that comprises Google Maps is loaded with such methods for the various actions you can take: search, get directions, zoom in and out, print, link, etc.

When another program wants to use Google Maps, it cannot physically press a button. It needs to call those methods within the code itself; that is, it needs to call them programmatically. And it can only call them if Google opens them to the public. Those shared methods are APIs—you insert them in your own application code in order to call the implementation code of Google Maps.

Say you want to create an app that displays, in Google Maps, all the coffee houses within a certain radius. You could attempt to write the entire program from scratch, recreating Google Maps code and mashing it with your coffee shop feed. But that would be a waste of time because Google Maps provides its API for free, and hence, programmatic access to the functionality encapsulated underneath.

In fact, someone has already created such an app called CoffeeSeeker. The website, Google Maps Mania, (http://googlemapsmania.blogspot.com/) lists tons of other Google Maps mashups. The video, What is a Mashup?, by David Berlind at ZDNet, is a good introduction to the concept of APIs and mashups (www.zdnet.com/videos/whiteboard/what-is-a-mashup/152729).

What Is a Web Service?

A Web service is a specific kind of API and is often referred to as a Web API. The big difference is that rather than implement the methods of another system in your own code, you send requests to that system. Put another way, a Web service is an API that uses a request-and-response architecture and is usually, although not always, executed over a network such as the Internet or an intranet.

But how do you know what to request? And how to request it? With a traditional API, you get an actual package of methods. With a Web service, you generally refer to a template from the Web service provider in order to make a valid request.

This template might be written in a language called Web Services Description Language (WSDL), a variant of XML, and referred to as “the WSDL” (pronounced WIZ-dull). Using this template, you create requests, perhaps in XML, that you send to the provider. The provider, in turn, sends a response in the same data format with the data you requested. Amazon.com is a Web service provider and you can see one of their WSDLs here: http://soap.amazon.com/schemas2/AmazonWebServices.wsdl.

Not all Web services use a WSDL, however. For example, to make requests to the Directions (Web) API in Google Maps, you simply pass your request in a URL such as this one for directions from Chicago to LA via Route 66: http://maps.googleapis.com/maps/api/directions/xml?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&sensor=false.

When you paste the URL above in a browser, Google sends back an XML response with directions (see Figure 1). Search the XML response for “html_instructions” and you will see the same route as on the Google Maps GUI (see Figure 2). By parsing the data in a Web service response, you can extract the data you need to build an application.

Web services come in different flavors. For example, to send information, they can use one of several protocols such as REST, SOAP, JavaScript, and XML-RPC. They can also have one of several data formats such as XML, JSON, RSS, and HTML.

For more context on Web services, see: 1) Introduction to Web Services, by Hasan Mir at ZeroToProTraining; 2) Janet Wagner’s article, “The Increasing Importance of APIs in Web Development;” and 3) Brian Suda’s thesis, “SOAP Web Services .” Of course, don’t forget Programmable Web.


Figure 1


Figure 2


What Is an SDK?

A Software Development Kit (SDK) is a tool, or set of tools, that help an application developer use an API. Some SDKs are as simple as the API itself—a library of API calls and classes. Others come with fancy tools to help you build programs in a particular environment. A typical SDK might include one or more APIs, an API reference manual, and sample code.

An SDK is sometimes confused with an Integrated Development Environment (IDE) such as Visual Studio or Eclipse. An IDE is an environment that makes programming easier, much like Word and FrameMaker make technical writing easier (than in Notepad). An SDK is the content with which you develop a particular application, whether in an IDE or with a text editor such as Vim. In sum, an IDE is a programming environment; an SDK is the API plus materials to help you understand and use that API.

Some SDKs come with an IDE plug-in so that you can use that particular SDK within your favorite IDE. The Android SDK, for example, comes in a vanilla version (that you can use in Vim, etc.) or as an Eclipse plug-in that lets you develop programs for the Android platform within Eclipse.

On the Job

Let us take a look at APIs and SDKs in the context of two real companies. I talked to Denise Green at Gracenote and Richard Smith at Netflix.

Working at a B2B

Gracenote, formerly known as CDDB, is an independent subsidiary of Sony that sells access to its large databases of metadata on CDs (and also DVDs) via APIs. Their music metadata, for example, is used in products such as Apple iTunes and Ford SYNC, which recognize and recommend songs based on your preferences.

From a developer’s point of view, Gracenote has some code; that code has an implementation (hidden, for private use only) and an interface (open, for public use by authorized developers). The developers at Gracenote implement the Gracenote API. The developers at Apple and Ford use the Gracenote API.

Suppose Gracenote has an API call named track.getArtist() that returns the artist for a given track. The Ford code uses track.getArtist() to get an artist; the Gracenote code contains the logic to query some database and return the artist associated with that track.

Ford doesn’t know and doesn’t care how Gracenote goes about getting the artist; it just works. Gracenote keeps the implementation hidden, but exposes the interface (API) to Ford.

It is Denise’s job to document Gracenote SDKs so that the software developers at Apple and Ford know how to use the appropriate API. This means she has to describe methods and write sample code using those methods. And she has to do this for several languages such as C++, Java, and Objective C, as Gracenote provides SDKs for multiple platforms.

Delivering the API and the App

We all know that Netflix rents DVDs and streaming video. What you might not know is that they also create APIs. TV manufacturers, for example, embed the Netflix streaming software into their own software so that you can access the Netflix movie catalog from your TV. Richard documents the SDK for that streaming software.

Netflix takes their SDKs a step further, and for some of their TV partners they write the application software, too. That is, they ship both the SDK, which their partners port, plus the “app” that uses the API in that SDK. They often do this because TV manufacturers work on extremely tight schedules. In retail, it’s all about seasonal shopping cycles, and you can’t reschedule Christmas, said Richard. For those who want to create their own differentiated app, Netflix provides design rules and guidelines.

Like Denise, Richard has to document SDKs for different platforms, but in his case, platform means the hardware architecture and components the TV makers use. Each TV platform is different, so what a developer needs to do to make the Netflix software work on that TV is also different. Richard has to understand each one.

Nuts and Bolts of Documenting APIs

The heart of documenting an API is commenting the code base by explaining what each method does, then generating documentation from those comments in the code. That is, you enter markup language in the code base, then perhaps run tools such as Javadoc or Doxygen against it to generate documentation.

Of course, getting permission to touch the code requires that the developers trust you. As Ed told me, you might need to prove that you are capable of entering doc comments without breaking the build. If you are competent, you may find yourself helping out in other ways such as recognizing and reporting bugs in the code itself.

API Documentation Deliverables

APIs need to be documented so that application developers know how to use them. A developer needs to know the structure of the API, the functionality of the API, and how to use individual software components, say Jim Bisso and Viki Maki in their book, Documenting APIs.

The heart of documenting an API is commenting the code base by explaining what each method does, then generating documentation from those comments in the code.

Joshua Bloch at Google thinks that a well-written API can be used without documentation; and yet, he says, “documentation matters.” From the PDF of his talk, “How to Design a Good API and Why it Matters”: “Document every class, interface, method, constructor, parameter, and exception.”

Traditionally, the two most important deliverables include a reference guide and a programmer’s guide. Again, from Documenting APIs, the reference guide describes “the constituent parts of the API, such as the classes and methods.” The programmer’s guide is more conceptual and “provides a description of how to use the API” and “often includes tutorials and practical examples.”

Charles Hoffman, an experienced API developer, told me what he looks for in API documentation:

Reference Guide
  • What the method does
  • What data should be provided to the method and what data will be returned
  • When the method should be used
  • When the method should not be used
  • Internal states being maintained, if any
  • Side effects, if any
  • Possible errors and exceptions and how should they should be handled
Programmer’s Guide
  • Concepts of use
  • Overview of the API and service being manipulated
  • Examples of initialization, use, and shutdown
  • Examples of common tasks

Richard Smith told me that today, more and more companies “are producing the same materials in topic-based documentation sets” rather than as a traditional “guide.” However you deliver your documentation, Ed emphasized that developers expect it to be complete, accurate, and well-organized.

The API Writing Process

While the approach to each job depends upon several factors, such as whether or not you receive a requirements specification, who the developers are, etc., the general process is something like this:

  • Gather source documents (code, functional specs, WSDL, bug reports).
  • Interview Subject Matter Experts (SMEs).
  • Document use of each class, method, etc.
  • Write code samples and tutorials.
  • Meet with developer to refine understanding.
  • Test and edit documentation.
  • Generate and deploy documentation set.

API writing is an iterative process of reading code, talking to SMEs, and writing stuff down.

Richard emphasized that he likes to interview multiple stakeholders before writing. He doesn’t look at the developer as the only SME and, if possible, starts with the API consumer.

Ed added that he likes to check the code versioning system for code changes and the bug tracking system for new API-related issues. If possible, he also likes to install and use the product.

Susan mentioned running the doc tool itself—when you build the code from a tool such as Doxygen, you can see if the developer added or removed comments.

How Can You Become an API Writer?

I asked my interviewees if they thought that a computer science degree is necessary for becoming an API writer. Of the four, only Denise has a computer science degree. So the answer is no. What is required, of course, is the capacity and enthusiasm to learn about computers and their associated fields of knowledge such as hardware, software, programming, networking, etc.

If you have the desire to get into API writing, here are some of the things you can do to get started:

Read Literature on Documenting APIs. A terrific resource is the online Developer Support Handbook by Pamela Fox at Google. She dedicates the first chapter to API documentation.

The only book I know of that specifically addresses API writing is Documenting APIs: Writing Developer Documentation for Java APIs and SDKS by James Bisso and Victoria Maki. To get it, contact James at http://bitzone.com/book.html. This book was published in 2006 and my understanding is that a new version is going to be published soon.

Programmable Web is a website that lists tons of APIs and publishes an informative blog. Another blog, directed at developers, is The Amiable API, which has a post specifically on writing helpful API documentation.

The LinkedIn group API Documentation can be useful. Also, don’t forget to scan other blogs. You can find useful posts, such as Writing an API Reference Guide for iOS.

Read API documentation. Read the developer websites mentioned throughout this article. It is the very stuff you are going to be writing yourself. Google’s API and Web service pages might be overwhelming if you are just starting out. Twitter presents their APIs more simply https://dev.twitter.com/docs/api/1/get/search.

Play with API documentation tools. The following tools allow you to document the code and generate help documentation from it.

Take courses. If you don’t know which courses to take first, refer to your chosen school’s certificate programs for guidance. For example, City College of San Francisco (CCSF) offers a range of certificates in both computer science and computer networking. And many of the courses are online.

Take advantage of open courseware. One of the more famous open courseware (OCW) sites is that by MIT: http://ocw.mit.edu/index.htm. A great place to start is with their entry-level course on structured programming using Python. This course is not about Python per se; rather, Python is used as a tool to teach the principles of computer science and the art of computing. For more OCW sites, refer to the open courseware consortium: www.ocwconsortium.org/en/courses/ocwsites.

Teach yourself to program. Free online schools and tutorials are popping up like mushrooms. Two of my favorites are Udacity.com, founded by Sebastian Thrun, and Codecademy.com.

Use an API and develop an application. Developing an app shows a potential employer that you understand code, how APIs work, and the overall process of implementing an application. Richard told me that the Twitter Search API is one of the easiest to use. To get started, you generally have to register at that site in order to get a key for access to the API. If something goes wrong, they need to know who you are. There is no reason to be afraid, even if you are just learning how to code. There are no “software developer” police so go ahead and register.

Gwendolynne Barr is a technical communicator and former software QA engineer who specializes in writing for software developers. She currently works at Thomson Reuters in San Francisco.

4 Comments

  • Gwendolynne,

    Thanks so MUCH! I need to document some APIs for our company and so far, my documentation is just a mismatch of fits and starts. This is VERY helpful!

    Joel Meier
    STC Rocky Mountain Chapter (http://stcrmc.org/)

  • Very well written article and very good advice. It’s refreshing not to read an article about documentation management for once.

    David Dick
    Fellow
    Co-author of “Web Services, Service Oriented Architectures, and Cloud Computing”

Click here to post a comment