What Is a Great API Documentation?

Let’s deep dive, how to first define an API Documentation?

An API Documentation is a technical document where one can find all information that is required to work with an API: functions, classes, return types, arguments etc. supported by examples. API description formats like the OpenAPI/Swagger Specification have automated the documentation process, making it easier for teams to generate and maintain those documentations.Yet, it’s interesting to remember that a few years ago, developers paid little to no attention to API documentation when building some.

‍

Why document APIs after all?

Over the last few years, the creation of API documentation tools increased. The reason behind this rise is quite simple: API documentation is key in any API related project. Why is that? Well, since APIs should be treated as real Products, APIs should then be considered as real “consumables”. To consume a Product, the end user needs to understand how it works, right? Here, when we speak about “the end user”, we mainly talk about Developers - that consume the APIs. These developers are always busy working on challenging topics. When they need to integrate an API, they want the integration to be smooth and quick in order to spend their time on higher value tasks. This means they should easily understand the documentation and should be able to test the API by themselves.
‍

To provide a nice Developer Experience, a great API Documentation is actually a prerequisite. There's more: documentation must be thought for different stakeholders (CTO and/ or Product Managers). Those stakeholders won’t actually use the API such as Developers but will quickly evaluate if the API is suited for their needs. How will they do so? Mostly by checking whether it is fitting to their use case.
‍

Let’s now get back in the shoe of an API Provider. While we still have in mind the API Developers and other Decision Makers an API Documentation should satisfy, let’s investigate a bit more.

As an API Provider, a good API documentation should make sure that you:

• Increase user adoption
  ‍Developers adopt the products they like to play with. When the documentation is done right, more developers want to use it. The same goes for decision makers: they like the ones they easily understand.
• Improve the network effect
  ‍Developers and decision makers are like anyone else: they like to spread the word when they like using a tool, the same goes for an API documentation.
• Decrease time and costs spent on API support
  ‍With an API Documentation done right, less time needs to be spent to onboard new users and support them in using your API. Countless hours spent to reply to support emails becomes a thing of the past.
  ‍

What’s then an example of a good API documentation?

Stripe API is an excellent example. Their API Documentation has nearly become a standard people try to follow in the industry. As Stripe folks mention in one of their articles, “an API product is more than just the API”. “There’s the documentation and developer products that supplement the integration experience”. This is part of what makes their API so great to use. Since Stripe is obsessed with customer experience, their API documentation has been built with the same logic: engage and build the product along with their customers. What we love at Blobr when using their API are the explanations on the left and the code snippets on the right. There is no need to search how the API is working. Everything is made simple and easy to understand. The final user experience is taken into account as it is easy to relate API endpoints and routes to a use case.

Another one that we should give credits to is the Twilio API. Quite similar to the Stripe API in terms of flexibility and user-friendliness!
‍

That being said, how to sum-up what makes an API Documentation nice and easy to use?

• Authentication
  Describing which authentication scheme your API uses.
• Resources
  Referring to the information returned by an API. An API has a number of endpoints grouped under the same resource. Resources need to describe both the general resources and the individual endpoints.
• API Console & Debugging Section
  Giving the ability to immediately test what developers see in the documentation.
• FAQ
  Working with FAQ where we know we can find answers to our questions is very helpful. At Blobr, we love that content type.
• Up to date dynamic layout
  Making sure the documentation is not outdated.That way, API Providers can also let consumers know how stable the API is.
  ‍

Now, what can be done to transform a good API documentation into a great one?

A great API Documentation does not assume only a certain level of knowledge but will make sure almost any user understands the content. Everything should be made to ease the use of the API for both Developers and other decision-makers who will work with the API - based on their use case.

For instance, let's take the example of a Hotel booking API from Expedia. The documentation details different routes like geography, shopping, manage booking and recommendations information included in specific routes. Each of these topics compiles different routes you can use. It is quite puzzling from a final user perspective to pick up the right elements from each topic and route to build its own use case.

‍

On the contrary, at Blobr, we preach for use-case specific documentation. This means creating a documentation that is adapted to the user's use-cases at stake. That really improves the user experience.For instance, you can have a first use case where you want to request data about rooms in Europe having reviews higher than 4 stars out of 5. Those rooms should also be located in a 30km radius from requested geography.You can have a second use case where you request data that only displays - as a Hotel chain - your hotel reviews and availabilities.Documentation is then built around the value provided for the end user and matches the use case exactly. You can have as many use cases as you want! Made that way, it helps the work of developers to associate different elements together. Another benefit is that you direct developers about the best way to use your API based on their use case. There will be less and less side effects of Developers making unexpected use of an API.

‍

‍
‍

That being said, while most people leave the task of drafting the API documentation to the very end, at Blobr, we think the API Documentation should be baked in at the time of building an API usage scenario for a use case.

We were so frustrated that only 10% of the documentation was used by our customers based on their use cases. We now automatically create a spot-on documentation based on API products and plans created by an API provider.

It is not a long API documentation or a well-written notice about what each element can do anymore. Blobr really helps to create instructions about how to use the API for a specific use case and it makes API documentation just great. Final users can see API examples for their exact use case with a customised content fitting their needs and with code snippets. Excited to keep improving the way documentation is made and used!

Discover how Blobr could be applied to your business by talking to our experts.