The market for REST API documentation
Before we dive into the technical aspects of APIs, let’s explore the market, general landscape, and trends with API documentation.
- Diversity of APIs
- Programmableweb API survey rates doc #1 factor in APIs
- Because REST APIs are a style rather than a standard, docs are essential
- The web is becoming an interwoven mashup of APIs
- Job market is hot for API technical writers
- API doc is a new world for most tech writers
Diversity of APIs
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 developers, and they incorporate this library into their projects. They can then call those classes or functions directly in 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
https://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 because 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 briefly in a Native Library APIs.)
Programmableweb API survey rates doc #1 factor in APIs
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. Programmableweb.com charts and tracks the number of web APIs added to their directory. Programmableweb says, “Since January of 2014, an average of more than 2,000 APIs have been added per year” (Research Shows Interest in Providing APIs Still High).
eBay’s API in 2005 was one of the first web APIs (the API allowed sellers to manage their products in their eBay stores). Since then, there has been 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.
Because REST APIs are a style rather than a standard, docs are essential
REST APIs are a bit different from the SOAP APIs that were popular some years ago. SOAP APIs (service-oriented architecture protocol) enforce a specific message format for sending requests and returning responses. As an XML message format, SOAP is very specific and has a WSDL (Web Service Description Language) file that describes 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 fuel the need for accurate and clear documentation. (I’ll explain more about REST APIs in the What is a REST API?) As long as REST APIs vary from one to another, there will be a strong need for technical writers to provide documentation.
The web is becoming an interwoven mashup of APIs
Another reason why REST APIs are taking off is that the web itself is evolving into a conglomeration of APIs. Instead of massive, do-it-all systems, websites are pulling in the services they need through APIs.
For example, rather than building your own search to power your website, you might use Algolia instead and leverage their service through the Algolia Search API. Rather than building your own payment gateway, you might integrate the Stripe API. Rather than building your own login system, you might use the UserApp API. Rather than building your own e-commerce system, you might use the Snipcart 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. Overall, the web is becoming an interwoven mashup of many different services and APIs interacting with each other.
Job market is hot for API technical writers
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 are what make it appealing. 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 doc is a new world for most tech writers
API documentation is often a new world to technical writers. Many of the components may differ from traditional GUI documentation. For example, all of these aspects with developer documentation differ from traditional documentation:
- Authoring tools
- Programming languages
- Reference topics
- User tasks
When you try to navigate the world of API documentation, you may be initially overwhelmed by the differences and intimidated by the tools and code. 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. From these early days, I realized that API documentation would be a hot topic, so I turned my focus toward this area for the next few years — giving more presentations, workshops, and all the while building this comprehensive course.
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 will fulfill a critical role in companies that distribute their services through APIs.
9/110 pages complete. Only 101 more pages to go.
Want to buy me lunch? Click the Donate button below to donate $10 through Paypal.