Before we dive into the technical aspects of APIs, let’s explore the market and general landscape and trends with API documentation.
The API landscape is diverse. In addition to web service APIs (which include REST), there are web socket APIs, hardware APIs, and more. Despite the wide variety, there are mostly just two main types of APIs most technical writers interact with:
With native library APIs, you deliver a library of classes or functions to users, and they incorporate this library into their projects. They can then call those classes or functions directly in their code, because the library has become part of their code.
With REST APIs, you don’t deliver a library of files to users. Instead, the users make requests for the resources on a web server, and the server returns responses containing the information.
REST APIs follow the same protocol as the web. When you open a browser and type a website URL (such as http://idratherbewriting.com), you’re actually making a GET request for a resource on a server. The server responds with the content and the browser makes the content visible.
This course focuses mostly on REST APIs because REST APIs are more popular and in demand, and they’re also more accessible to technical writers. You don’t need to know programming to document REST APIs. And REST is becoming the most common type of API anyway. (Even so, I also cover native library APIs in a later section.)
Before we get into the nuts and bolts of documenting REST APIs, let me provide some context about the popularity of the REST API documentation market in general.
In a 2013 survey by Programmableweb.com (which is a site that tracks and lists web APIs), about 250 developers were asked to rank the most important factors in an API. “Complete and accurate documentation” ranked as #1.
John Musser, one of the founders of Programmableweb.com, emphasizes the importance of documentation in his presentations. In “10 reasons why developers hate your API,” he says the number one reason developers hate your API is because “Your documentation sucks.”
If REST APIs were an uncommon software product, it wouldn’t be that big of a deal. But actually, REST APIs are taking off in a huge way. Through the PEW Research Center, Programmableweb.com has charted and tracked the prevalence of web APIs.
eBay’s API in 2005 was one of the first web APIs. Since then, there has been a tremendous growth in web APIs. Given the importance of clear and accurate API documentation, this presents a perfect market opportunity for technical writers. Technical writers can apply their communication skills to fill a gap in a market that is rapidly expanding.
REST APIs are a bit different from the SOAP APIs that were popular some years ago. SOAP APIs (service-oriented architecture protocol) enforced a specific message format for sending requests and returning responses. As an XML message format, SOAP was very specific and had a WSDL file (web service description language) that described how to interact with the API.
REST APIs, however, do not follow a standard message format. Instead, REST is an architectural style, a set of recommended practices for submitting requests and returning responses. To understand the request and response format for REST APIs, you don’t consult the SOAP message specification or look at the WSDL file. Instead, you have to consult the REST API’s documentation.
Each REST API functions a bit differently. There isn’t a single way of doing things, and this flexibility and variety is what fuels the need for accurate and clear documentation. As long as there is variety with REST APIs, there will be a strong need for technical writers to provide documentation for these APIs.
Another reason why REST APIs are taking off is because the web itself is evolving into a conglomeration of APIs. Instead of massive, do-it-all systems, web sites are pulling in the services they need through APIs.
For example, rather than building your own search to power your website, you might use Switftype instead and leverage their service through the Swiftype API. Rather than building your own payment gateway, you might integrate Stripe and its API. Rather than building your own login system, you might use UserApp and its API. Rather than building your own e-commerce system, you might use Snipcart and its API. And so on.
Practically every service provides its information and tools through an API that you use. Jekyll, a popular static site generator, doesn’t have all the components you need to run a site. There’s no newsletter integration, analytics, search, commenting systems, forms, chat e-commerce, surveys, or other systems. Instead, you leverage the services you need into your static Jekyll site. CloudCannon has put together a long list of services that you can integrate into your static site.
This cafeteria style model is replacing the massive, swiss-army-site model that tries to do anything and everything. It’s better to rely on specialized companies to create powerful, robust tools (such as search) and leverage their service rather than trying to build all of these services yourself.
The way each site leverages its service is usually through a REST API of some kind. In sum, the web is becoming an interwoven mashup of many different services from APIs interacting with each other.
Many employers are looking to hire technical writers who can create not only complete and accurate documentation, but who can also create stylish outputs for their documentation. Here’s a job posting from a recruiter looking for someone who can emulate Dropbox’s documentation:
As you can see, the client wants to find “someone who’ll emulate Dropbox’s documentation.”
Why does the look and feel of the documentation matter so much? With API documentation, there is no GUI interface for users to browse. Instead, the documentation is the interface. Employers know this, so they want to make sure they have the right resources to make their API docs stand out as much as possible.
Here’s what the Dropbox API looks like:
It’s not a sophisticated design. But its simplicity and brevity is one of its strengths. When you consider that the API documentation is more or less the product interface, building a sharp, modern-looking doc site is paramount for credibility and traction in the market. (I dive into the job market for API documentation later.)
API documentation is often a new world to technical writers. Many of the components may be new. For example, all of these aspects with developer documentation differ from traditional documentation:
When you try to navigate the world of API documentation, you may be initially overwhelmed by the differences and intimidated by the tools. Additionally, the documentation content itself is often complex and requires familiarity with development concepts and processes.
Realizing there was a need for more information, in 2014 I guest-edited a special issue of Intercom dedicated to API documentation.
You can read this issue for free at http://bit.ly/stcintercomapiissue.
This issue was a good start, but many technical writers asked for more training. The Silicon Valley STC chapter held a couple of workshops dedicated to APIs. Both workshops sold out quickly (with 60 participants in the first, and 100 participants in the second). API documentation is particularly hot in the San Francisco Bay area, where many companies have REST APIs requiring documentation.
Overall, technical writers are hungry to learn more about APIs. This course will help you build the foundation of what you need to know to get a job in API documentation and excel in this field. As a skilled API technical writer, you will be in high demand and fulfill a critical role in companies that distribute their services through APIs.
6/93 pages complete. Only 87 more pages to go...
If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson