Why your API Doc Structure Matters: How these 5 Principles make it easy for your readers

Common Issues with API Docs: And How I Managed to Solve Them

Good API Documentation is crucial for developers to understand and utilize the APIs in the best way possible, And it can contribute to the success of the project.

A Project without good documentation is like a tool without proper instructions. No matter how good the tool is, if people don't understand, it's useless. So we need a proper idea of what common mistakes people commit when making API documentation for their project.

1. Discovering the right API that I need

When a developer enters your documentation, they will usually have an specific goal in mind. They will be searching for an API which they need from your documentation.

Example: Suppose your API docs includes an endpoint for sending emails
If the developer searches with "email" then the relevant endpoint should come up right away.

If the API Documentation has poor search functionality and unorganized documentation structure, the developer can get exausted trying to find the API they need.

The solution towards this problem is to implement a proper search functionality as well as a documentation structure.

Divio has a good structure that helps to easily grasp the contents.

This system divides documentation into 4 main types

1. Tutorials (Learning Oriented): Designed to teach, help a developer to acheive something from start to finish

2. How-To Guides(Problem oriented): Helps to solve a particular problem step by step

3. Explanations (Understanding oriented): Provides in-depth explanations about how things work

4. Reference(Information oriented): Serve as a technical resource if you need specific details

2. Figuring out how to use it

When API documentations are made, We can often forget that this documentation is meant to be read by a developer who has no prior experience working with the system. So the they can often be left wondering what the endpoint does and what is the bigger picture in which this API belongs.

To solve such issues, we need a detailed description, which should be beginner friendly, and should demonstrate real-world usecases

Example:
Suppose the following API is shown in the documentation:

https://dogapi.dog/api/v2/breeds/{id}

The user might not immediately know what the API does or what value to insert for {id}.

To resolve this, the documentation needs a clear description and a real-world example, like:

The API (https://dogapi.dog/api/v2/breeds) provides detailed information about various dog breeds. This API allows users to retrieve specific data related to dog breeds, including attributes like name, physical characteristics, life expectancy, weight, temperament, and other related details.

https://dogapi.dog/api/v2/breeds/68f47c5a-5115-47cd-9849-e45d3c378f12

3. Procrastination in creating the code and getting it done

Even if the documentation is well-defined, the developer may still feel some friction in integrating the API into his code. As a solution to this problem, we can have code snippets in various languages that can be generated from the API.

The developer can directly copy and paste these snippets into his code and get things running quick.

For example
A python developer will prefer a ready made request like

import requests

url = "https://dogapi.dog/api/v2/breeds/68f47c5a-5115-47cd-9849-e45d3c378f12"

response = requests.get(url)

print(response.json())

Rather than a plain url

https://dogapi.dog/api/v2/breeds/68f47c5a-5115-47cd-9849-e45d3c378f12

4. Handling Errors and Authentication

Imagine a new developer who is using your API encounters an error or faces an issue related to authentication.The first place they would look is your Documentation, to see what are the possible errors and the solutions which can be applied.

But if the documentation doesn't have such information, then the whole debugging process can become painful. This can even lead to the user ultimately dropping off from your API and searching for easier alternative solutions.

We can solve this problem by listing the common errors, showing detailed troubleshooting solutions and link towards how the authentication tokens are to be obtained.

For example:

Imagine a developer trying to access a protected API endpoint, but faces errors.

The API docs should demo how to use the authentication token like

curl -X GET "https://httpbin.org/bearer" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

And show the possible errors like so.

How Mainstream API Docs Structure Information for the Readers: A Case Study

Mintlify

For our Mintlify example, let's visit the infisical documentation.

Suppose, I want to look for an API for Creating Client secret. There are 2 ways in which I can access it. One is to go through the Auth-related categories and find them. Or I can use the search bar and search for "Client secret". It's pretty straightforward to get the APIs we need.

Since we got the API we need, We need to understand it next. Details are provided related to Authorizations, Path parameters, Body, and Response.

Now we have understood the API. The next thing to do is get the implementation done. We have the code snippets in various languages (cURL, Python, Javascript etc) as well as the responses to see what it looks like.

Readme

Let's explore the Readme documentation.
We will be visiting persona documentation for this.

The UI consists of a sidebar and a topbar. We can see the Topbar having OpenAPI Spec, which is a standard format for defining RESTful APIs, allowing for clear documentation and interaction with the API. This also means the documentation is synced with the OpenAPI Definition, ensuring the details in the documentation are always upto-date.

There is an API Changelog as well, so each changes are tracked.

Suppose we want to use the Create Authorization API. I can either go to the OAuth section or the search bar to get the API.

To understand how the API works, I can utilize the "Try it" button to run the API myself and observe what the output looks like.

For deeper understanding, we have sections like Form-Data, Headers, and Responses.

We can also observe an Alert, which informs the user about the prerequisites.

Fern

At last, we can check the Fern Documentation.
We will be visiting Vellum documentation.

We will try searching for Execute Prompt API. This API can be similarly accessed via the search bar or the sidebar.

For understanding the API, we have a play button to try the APIs ourselves as well as some description about the Request and Response.

Based on our learnings, we now know the features that these API Documentation platforms use. Let's go through it one by one.

The Key features that improve Developer Engagement

Playground

A playground offers the developers an interactive environment where they can experiment with the APIs, This makes the API learning more practical and helps the user to become onboarded more easily.

Neat structure

Every API documentation we have gone through earlier has a clean structure, with each API having their respective sections and search functionality as well.

OpenAPI Spec and Syncing with the latest API

With OpenAPI integrated into the documentation, whenever an API definition changes, we can modify the OpenAPI Spec and the changes will be reflected in the docs accordingly.

Multi Code generation

Offering code generation in multiple programming languages increases the accessibility of the API, and having ready to use code snippets makes integration faster and more appealing.

Versioning

If there are various versions of the API present, versioning will be helpful as it will point the developer towards the right direction when they want to use a specific version of the API.

The 5 Doc Principles to Drive your projects success

1. Discovery of APIs easily

• Users should be able to find the right API endpoints effortlessly, either through a search bar or navigation menus
• Organizing the documentation into well-defined categories ensures that developers can locate relevant APIs without getting overwhelmed.
• Table of contents helps the developer to grasp the contents at a more faster pace
• Faster discovery and onboarding to the API leads to quicker adoption.

2. Easily understandable

• Clear descriptions, paired with practical and real-world scenarios give developers context and insight into how to effectively use the API in their projects.
• Avoid technical jargon and focus on clarity to make the documentation friendly for new developers

3. Easy to implement

• Offering try-it-yourself options, where the developers can try the API themselves allows for experimenting without leaving the documentation.
• Code generation in popular languages reduces time spent on implementing the API and makes it more accessible.
• Smooth integrations create positive opinions and leads to more customers adopting your API.

4. Help with Sharing and Teaching

• Clear version history, with deprecation warnings helps developers stay up-to-date and prevents confusion when teaching or adopting new versions

5. Help with Customization

• Show how the API can be adapted to various use cases, and provide sample implementations.
• Guidance on how to tweak the API to handle different environments like development testing and production.

Guide to building own API Docs: Hands-on Techniques

You don't need to necessarily depend on any API Documentation platform, you can build your own as well from the open-source API documentation that are available. For this Demo, I will be using Mkdocs.

1. Taking a suitable theme from mkdocs

• You can visit the mkdocs themes page and choose a suitable theme which you like.
• For my case, I used a theme called dracula.
  

2. Cloning the theme and setting the local environment

Create a new mkdocs project with a name (eg: myproject)

mkdocs new myproject

Clone the theme repository.

git clone git@github.com:dracula/mkdocs.git

Copy the mkdocs_dracula_theme and template folder into the myproject folder

Change the mkdocs.yml file to the following.

site_name: "your_site_name"
repo_name: your_repo_name
repo_url: https://github.com/your_username/repo_name
site_url: https://your_site.com
copyright: MIT
theme:
 name: null
 custom_dir: 'mkdocs_dracula_theme/'
 static_templates:
  - 404.html
 locale: en
 include_search_page: true
 search_index_only: false
 highlightjs: true
 hljs_languages: []

This will set the theme to the mkdocs_dracula_theme directly you just copied.

3. Modifying the theme to own use

I will be adding our own Code Generator and API executor called LiveAPI to the documentation

You can add them by modifying the YAML file and copying a js folder into the docs directory. (Repository Link)

Add the following scripts to the mkdocs yaml file.

extra_javascript:
 - js/widgetla.js
 - js/disable_shortcuts.js

I have also experimented with the UI a bit and modified it to my own use, (You can do so by tweaking the HTML files)

This is my result

• As you can see, there is a sidebar for easy navigation with categorization
• Description of the API
• Details about query Parameters
• LiveAPI Widget to try the API and generate Code snippets
• Response codes and their meanings
• OpenAPI Link on the topbar
• Search box for accessing the API

Conclusion

A well-structured API documentation is essential for ensuring the success of your API by making it accessible, understandable, and easy to use.

It's crucial to continuously improve your API documentation based on user feedback, addressing any unclear areas.

For our future work, we plan to set up a system that automatically generates documentation from a developers GitHub repository, ensuring the format is human-friendly and supports OpenAPI.

You can follow me on my Twitter to stay updated on the progress.