When it comes to embarking on a web API documentation journey, first and foremost, one should cater to a seamless developer’s experience, improved adoption, and easy implementation of API at every stage of this journey. Companies like Facebook, YouTube, Microsoft, PayPal, and DropBox – which use internal and public APIs – are putting API documentation at the center of their policy.
The Google Maps API documentation proves that API does matter:
An API provides an interface for users, typically software developers, to pull what they need from your software and integrate it into their application.
Does it sound like API documentation is gaining more importance? For sure, it is. As of today, nobody has really preached about the benefits of web API documentation. However, nowadays a growing number of companies seem to be discovering the importance of documentation as a key to a better experience when implementing APIs.
In this blog post, we will explore best practices for API documentation and provide you with a brief round-up of top best tools for documenting APIs. Let’s figure out together the bare bones of API and how documentation fits in. We will offer illuminating insights into API essentials and then switch gears and focus on peculiarities of API documentation and tools that can come in quite handy. Whether you are a non-technical person or a software developer, you will find this blog post useful, since it gives a complete picture into the API world. So without further ado, let’s get started.
What an API is and Why Bother?
According to data from HBR, 2016 was a fruitful year for the API industry. Salesforce generates 50 percent of its revenues through APIs, eBay nearly 60 percent and Expedia a whopping 90 percent.
Have you ever wondered how Facebook is able to automatically display your Instagram photos? What about how Uber tracks your location? In fact, each time you check the weather on your phone, use the Facebook app or send an instant message, you are using an API. API stands for Application Programming Interface. What an API really does is allow two applications to exchange information in a standard and predictable way. It enables to add services and functionalities to the existing products.
We are, however, going to dwell upon a web API, otherwise known as a web service that provides an interface for web applications, or applications that need to connect to each other via the Internet to communicate. A web service is a piece of software, or a system, that provides access to its services via an address on the World Wide Web. This address is known as a URI or URL. A web service uses HTTP to exchange information. When an application, the “client”, wants to communicate with the web service, the application sends an HTTP request. The web service then sends an HTTP response.
The key terms we should learn:
- Server: a powerful computer that runs an API.
- API: the ‘hidden’ portion of a website that is meant for computer consumption.
- Client: a program that exchanges data with a server through an API.
In a nutshell, in order to make a valid request, the client needs to include four things:
- URL (Uniform Resource Locator)
- List of Headers
There are four methods most commonly seen in APIs:
- Get – asks the server to retrieve a resource.
- Post – asks the server to create a new resource.
- Put – asks the server to edit/update an existing resource.
- Delete – asks the server to delete a resource.
HTTP responses have similar structure to requests. The key difference is that instead of a method and a URL, the response includes a status code. It is a three-digit number that has a unique meaning. For example: 404 means ‘not found’, 200 – ‘success’, meaning that request was good, 503 – ‘API is currently down’. However, the response headers and body follow the same format as requests.
In order to understand better what API is, watch this helpful video from MuleSoft
Things are starting to pick up in our understanding of APIs.
Before we jump into different documentation tools, it’s important to understand what makes for good documentation.
Agile documentation often evokes contagious yawns not only in technical writers but also in developers, especially regarding APIs.
The API documentation helps to define the concepts before implementation and also helps to clarify how they see the world.James Higginbotham
Say you have developed a web API and want to share it throughout your enterprise or with the whole world, and guess what – here comes documentation.
According to SmartBear’s 2016 State of API Report, 75% of organizations that develop APIs now have a formal documentation process. 46% say it is a high priority for their organization.
A survey by ProgrammableWeb found that API consumers considered complete and accurate documentation as the biggest factor impacting their API decision-making, even outweighing price and API performance.
Confusing, out-of-sync API documentation makes for an unwelcome adventure. This danger leads to frustrated developers utilizing competitor’s solutions instead of yours. In this section we will tell you how to engage developers and make them choose your piece of API documentation.
Unlike coding, you’re writing for an audience of humans, not computers. It is a tricky task to write for developers, as they are demanding and critical. It’s hard to know where to start and how to do more with less.
The challenge is that
While planning your API documentation, it’s better to know who are you targeting at beforehand. The are two types of API consumers:
- API users – developers who want to integrate with your services and are looking to resolve a specific issue using your API.
- API decision makers – people who will be evaluating your services and seeing if it solves a strategic need.
The main thing is to write for humans, meaning not to overload the text with technical jargon and sophisticated terms. Using plain language always adds value to your document.
Pieces of advice for writing open source web API documentation:
- It’s better to follow common conventions rather than forcing users to learn your own system of brackets, braces, angle brackets in order to read your documentation.
- One should use the inverted pyramid writing style. Provide the most important information first, then progressively less important.
- Syntax diagrams (especially railroad diagrams) are also helpful as they provide a very clear, readable way to describe the syntax of commands and options.
- It is obligatory to give code examples for multiple languages, including all necessary code.
- One also must show examples of requests and responses.
- It is important to cover frequently asked questions & scenarios with code examples.
- It is also great to provide links to additional resources (other examples, blogs, etc.)
- All users like when there is a comments section where they can share & discuss code.
- The greatest thing is, however, when you provide interactive experiences for users to try & test API calls (API Console, API Notebook).
Tools to Generate Beautiful Web API Documentation
In fact, one may get lost in the sea of API documentation tools. Therefore, we are pleased to present you with our picks for top best tools. Running API documentation seems to be a rather tedious task. So get off your hamster wheel and automate this boring stuff with these gorgeous applications.
James Higginbotham pointed out API tools “are great for documenting the API, but not actually defining it.” That’s, indeed, the human’s job. It’s true we should treat API documentation automation as an assistant that we can delegate some tasks to, but not as a comprehensive tool that can to all the work for us.
Slate was developed by Robert Lord when he was interning at Tripit. It helps one to write API documentation by hand using Markdown (a lightweight markup language with plain text formatting syntax). Slate generates a three columned layout; company logo with method filtering on the left, API description in middle, and code snippets on the right. By default, your Slate docs are hosted on Github Pages, so you can have free hosting. It is a free static documentation tool that needs Ruby in order to be installed. Here is the example of Travis CI API documentation created in Slate.
Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but it also supports other programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL, Fortran, VHDL, Tcl, and to some extent D. To document your API, generate an online HTML documentation browser or an offline reference manual and configure Doxygen to extract the code structure from your source files. Doxygen is developed under Mac OS X and Linux, but executables for Windows are also available. Doxygen is free software, released under the terms of the GNU General Public License version 2.
Apidox is a free to use, open source, live Interactive API documentation application. Apidox is a small, simple and powerful PHP tool that creates a documentation from API XML structure definitions or annotations in your source code. It has a powerful interface for executing live API calls right from your API documentation. It provides one place for docs and testing. It supports online testing APIs as well as static samples definitions including errors codes, samples and information for every method.
Dexy is a powerful flexible tool for writing any kind of technical document incorporating code. Dexy helps you write correct documents and maintain them over time as your code changes. It supports any language, including documenting Web APIs. Dexy is able to run your example code, save the results, fetch data from an API, and post your docs to a blog or a wiki. Dexy is an open source software with an MIT license, written in Python.
We, plus a buncha experts including Ted Epstein, a CEO of RepreZen, believe that good API documentation is crucial for company’s success.
A Final Thought
If we were to apply the KISS principle – which means ‘Keep it simple, stupid’ – to API documentation, we would find it easier to maintain and consume APIs. This phrase has been associated with aircraft engineer Kelly Johnson and states that
Knowing about all the peculiarities of web API documentation will make your journey fun and carefree. Now that you have a sense of what API is and are brave enough to take a stab at creating your own API documentation, go forth and enjoy the journey! Do you know more API documentation tricks? Share your ideas and let’s discuss them in the comment section below!