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.

When two systems are integrated via API, there is two sides in this integration: client-side and server-side. Client-side means that the action takes place on the user’s (the client’s) computer. Server-side means that the action takes place on a web server. The client of a website refers to the web browser that is viewing it. The server of a website is, of course, the server that hosts it. The server-side programming is writing code that runs on the server, using languages supported by the server (such as Java, PHP, C#). Client-side programming is writing code that is done almost exclusively in JavaScript.

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:

  1. URL (Uniform Resource Locator)
  2. Method
  3. List of Headers
  4. Body

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.

API 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

API and Microservice Architecture Coach, LaunchAny

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.

Smooth developer experience depends directly on comprehensive web API documentation.CLICK TO TWEET

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

Documentation should be consistent not only in its appearance, but also with the functionality of your API.CLICK TO TWEET

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).

Here are the examples of websites with great web API documentation: Stripe, TwilioDropboxGoogle Maps.

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.

Swagger is a free, open source API framework to design, build, and document APIs. It’s a language-agnostic tool, meaning it can be used with multiple coding languages. Swagger is used both to generate API server code, client code, and the documentation for those services. Swagger focuses on streamlining and synchronizing the update workflow. Because the server and client code is generated and documented at the same time, they can be updated simultaneously. It’s comprehensible for developers and non-developers, because of its well-structured and good-looking  interface. Swagger is automatically generated from a Swagger specification and allows developers to interact with an API’s resources. Since it is open source on Github, the project can be downloaded, and hosted in any environment. The project’s HTML, CSS, and JavaScript assets will turn a Swagger specification into a human readable presentation, with a wide page dropdown template that documents each method, parameter, and operations. Swagger UI has a “Try this” button, which makes it a breeze to test out APIs.

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

Most systems work best if they are kept simple, and unnecessary complexity should be avoided.CLICK TO TWEET

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!