In the previous blog post, we’ve described all the must-haves the API reference should include from the content standpoint. This blog post is for those who want to go beyond the mandatory and explore the mystical land of bonus content that may help elevate the quality and usability of your API documentation. 

Let’s take a closer look at some nice-to-haves that you may consider including in your API docs. 

Links to Additional Reference Materials

A comprehensive API documentation should not operate in isolation. Providing links to additional reference materials, such as tutorials, guides, and related resources, enriches the user experience. 

Users can explore beyond the basics, gaining deeper insights into the functionality and possibilities offered by your API. To an experienced API user or creator, these may be quite immediate to catch from the reference. Still, for people new to the industry or programming, such links can offer quite literally light in the dark tunnel of understanding how to work with that API. 

Similarly, if you already have built SDKs around your APIs, here’s a chance to advertise them. Many developers will prefer to use them straight away, especially if they want to check out how your API works in a quick and hassle-free manner. 

Workflow and Main Concepts Exploration 

Help users navigate through the intricate details of your API by explaining workflows and main concepts. Linking out from the reference material to dedicated sections that provide a broader understanding of how different components work together ensures a smoother learning curve for those who need more context. 

Help and Support Information 

Don’t make users hunt for help and support. Include relevant information, such as FAQs, contact details, or links to support forums, so users can easily find assistance when needed. A well-supported API builds trust and satisfaction among its user base. It shows that the team behind the API really cares about their users and wants to connect with them. 

Building a strong community around an API has a lot of benefits for the API creators themselves. Not only does it build trust for the API, but it can also serve as the first line of support as the community members try to help each other with their struggles, or provide guidance for the newest members by helping with their projects. 

Consistent Naming Conventions 

Consistency is key. Ensure that endpoints, fields, and labels follow a uniform naming convention. A well-defined structure not only makes the documentation more professional but also enhances user comprehension, reducing confusion and potential errors. This is especially true for those with a big API stack who want to minimize their new users’ entry level.  

Consistency works wonders for the brain. It alleviates the cognitive load and makes it easier to spot connections, retain information, and scan new content efficiently without wasting energy. 

If you want your users to switch effortlessly between your APIs, work with other teams to make your APIs as consistent as possible. 

This is true for both design and content. Design-wise, make sure your APIs consistently use the same rules for: 

• The structure of URLs 
• How variables are represented 
• How plural and singular resources are represented 
• How you name your endpoints (use verbs to define actions and nouns for exposing resources) 

Since this post is more about content than anything else, I’m going to be a bit more specific about content consistency. 

Endpoints

Follow the naming convention that you created or change it to something you wish to practice moving forward. The point is that once you start doing something, you should stick to it across the entire API stack. For instance, if you decide to capitalize every word in an endpoint, do it for all of them. If your Table of Contents omits articles, e.g. ‘Update SMS message’, stick to it. 

Content Grouping and Labels 

If you decide to group your content so it’s easier to find, do it for every API you document. It is a very good practice and makes navigating through a table of contents easier, especially since an API is typically quite robust, and it’s easy to get lost in the jungle of different endpoints. 

Again, the most important factor is consistency. So, it doesn’t really matter if you decide to use a folder structure, titles, or expandable mini menus in your Table of Contents. It matters that you do it consistently for all your APIs. 

Descriptions

Think about how you want to present your information and make a list of content rules. You can then reinforce them automatically by adding some linting rules and regex or rely on a style guide. At Infobip, our API field descriptions need to: 

• Always end with a full stop. 
• Use the Oxford comma. 
• Exclude articles at the beginning of a description if it starts with a noun. 
• Document all examples using the example tag. 
• Document a list of accepted values using the enum tag. 
• Use backticks for values and parameter names. 

API Status 

Keep users informed about the current status of your API. Whether it’s operational updates, planned maintenance, or known issues, transparency instills confidence in users and helps them plan their development activities accordingly. 

This might be a no-brainer for some, but I think it’s still worth mentioning as something you should include in your API reference. I’ve seen many companies do it already, but I have also seen many that just stick it in the footer of their main page for the user to find. 

API status needs to be easily findable, especially from the level of developer documentation. And yeah, you can keep it in the footer, but make it available from any developer doc site so that it’s easily findable whenever somebody wants to check it. 

User Feedback 

Explore different approaches to gathering user feedback that is more direct than traffic site analytics tools like Google Analytics. If you decide you are ready to take a plunge into direct user feedback, there’s some level of engagement to think of, each with its pros and cons. 

Typically, developer docs go for sentiment buttons, which is a great way to see whether the article was helpful or not to the readers. 

The sentiment button is often accompanied by a quick form or an input-based window to provide more personalized feedback. This is an amazing way to discover developer pain points, among other things, like some colorful swear words of those who relieve their frustration through feedback, which is also good feedback in itself. This means that the particular page stirs the audience’s emotions, and it’s time to investigate the cause. 

Sandbox or a Postman collection 

A very appreciated nice-to-have is a sandbox environment for developers to see the code in different languages in action.  It is of course also a very expensive nice-to-have, so at least make sure some of your APIs provide up-to-date Postman collections presenting scenarios you wish to showcase to your audience. And remember, it is not about a collection of random endpoints, but rather a collection of workflows presenting how to use your API for some specific reason, e.g. sending a message, checking out a basket, etc. 

A sandbox or a Postman collection provide an environment where developers can experiment with the API. It offers a space for hands-on exploration and allows users to test functionality in a controlled setting, fostering a deeper understanding of your API’s capabilities. 

Never-ending journey to perfection 

As you navigate the mystical land of the API documentation, remember that having an open mindset about your documentation is crucial. It is never done, and there’s always room for improvement based on your audience’s needs. With that in mind, you will never write something just for the sake of writing. You will never forget that at the end of the day, it is not you, the API creator, but the API users who you write for, and you will make sure your content is user-friendly and often revisited for accuracy and consistency. 

I hope this article was helpful, and with that, I wish you all happy documenting! 😊