Types of API Documentation to Know About

Davor
Davor
Davor is a content marketing expert who loves writing about project management, productivity, and remote work.

There's more to API documentation than listing functions and endpoints. In this article, we'll go over the types of API documentation you should know about before settling on one way to present your API.

With 89% of developers using APIs in their work, API documentation is too important to take lightly.

And merely listing API references doesn’t cut it anymore—if you want your API to succeed, you’ll have to create more documents that explain its ins and outs.

In this article, we’ll explore how you can document your API to cover all its aspects, and learn about the different types of API documentation.

You’ll see that well-documented APIs don’t only make your users’ lives easier but can also help make your software more attractive to new customers.

We’ll start with an obligatory part of API documentation: code examples.

Code Recipes and Examples

You’ll have to dig deep to find an API document with no code examples.

This popular type of API documentation lets developers try out the API and see how it performs, making it the perfect opportunity for businesses to showcase their software solutions.

If you want another take on how code examples contribute to API documentation, you can think of them as recipes.

Like recipes, code examples are more of a guide than rules set in stone.

You can play around with them, add, delete, and modify the elements, and tinker with the code so that it fits your purpose the best.

Even developers have embraced the analogy and frequently use it to describe code samples.

For instance, the author of this repository uses food items to identify each React hook in the library.

GitHub react recipes
Source: GitHub

Remember, Julia Child wouldn’t mind if you added another pinch of salt to a recipe, and API authors definitely don’t mind the users tweaking the code to utilize the API the best they can.

However, if you want developers to use your code, you have to make it accessible. That’s why most API documentation contains copy-pastable code.

You should also read: 6 Tips for Writing Great API Documentation

Shopify’s API documentation goes one step further and incorporates a handy Copy button into each code sample, shortening the already quick copy+paste process.

Shopify’s API documentation
Source: Shopify

An additional reason why Shopify is an excellent role model for API code examples is that the authors have written a clear description of each code example, clarifying what it does.

\percentage or fixed-amount discount code
Source: Shopify

No matter how intuitive your documentation is, people will still find ways to misinterpret it, resulting in less-than-ideal outcomes.

However, descriptions written clearly like these will ensure that the developers turn your examples into successful APIs.

So, besides listing the code ingredients, you should ensure that your API examples also include informative explanations—that’s how you create a complete API recipe.

In-Depth Topical Guides

Sometimes isolated pieces of code don’t do your product justice. To demonstrate the full potential of your API, you can create a topical guide, our next API documentation type.

Here we recommend to read: 7 Steps to Writing API Documentation.

In this section, we’ll analyze in-depth topical guides using an example from the documentation created by Stream, a company producing API for chat and activity feeds.

Simple overviews and API tours are a great way to attract potential customers. For instance, Stream offers an API tour that simulates the implementation of the solution.

All code is there; you just click buttons and watch the product take shape.

Flat Feeds on Stream
Source: Stream

However, if you want to offer a deep dive into your API, you’ll need to cover its specialized areas.

Topical guides written for knowledgeable technical audiences show the ideas and conceptual aspects behind the API and its design.

While this type of API documentation requires more time to create, it can convince high-level customers of your API’s quality.

Stream begins the API topical guide by introducing the key concepts connected to the core element of the product, feed organization.

Feeds 101 on Stream
Source: Stream

Now, an average dev doesn’t have to fully understand these concepts to implement the solution successfully, but an overview like this one can help paint the picture of the solution as a whole.

Similarly, you can use an in-depth topical guide to showcase the design and architecture behind your software, as Stream does here.

Fan-out on Stream
Source: Stream

By reading the rest of the documentation, users can learn more about the details of the API.

All in all, in-depth topical guides may not be the most straightforward way to present an API, but they’re undoubtedly an asset that elevates the API documentation.

They allow you to create a narrative around your API and showcase all the intricacies behind it, demonstrating that you’ve scrupulously covered all the bases of the API.

Reference Guides‌‌

Reference guides are the most clear-cut type of API documentation.

They dissect the API and list all the information you need to work with it, such as details about methods, classes, functions, and more.

API references usually follow the same structure, which makes them relatively easy to compile. Common elements in reference guides cover:

  • Functions
  • Classes
  • Parameters
  • Return types
  • Arguments
  • Properties

And here’s what that looks like in practice, as seen in Square’s API reference guide.

Square’s API reference guide
Source: Square

As you can see, the Customers API is divided into parts concerning customer profiles, from listing customers to adding group memberships.

Each endpoint is prefaced with a concise description and supplemented with a code example. You can also see query parameters and response field information.

Although reference guides contain the crucial data you need to use APIs, you shouldn’t only rely on references to describe your API.

According to Gregory Koberger, the founder of ReadMe, reference guides should only be used as references, not as a substitute for API documentation altogether.

“You wouldn’t hand someone a thesaurus and expect them to learn English; in the same way you shouldn’t hand someone reference guides and expect them to learn how to use your API.”

To sum up, if you want to provide your users with a clear overview of your API, you should, by all means, create a reference guide.

Just don’t forget to supplement it with other document types to make your API even more comprehensible.

Support Forums‌‌

What if we told you that you can partially outsource your API documentation and enrich it with valuable input from real-life users?

That’s right; support forums are an excellent type of API documentation that lets you cover all the edge-cases without cluttering the primary documents.

If you described absolutely every scenario possible with your API, people would find your documents difficult to read and possibly abandon the product.

Enter support forums.

These digital spaces allow you to address the issues the users encounter and keep the knowledge publicly available.

We’ll now look at a Unity support forum question that has remained helpful for years after it was originally posted.

API for SceneView class
Source: Unity

The original Unity documentation didn’t cover the API for SceneView class, so the user turned to the community for help.

Unity probably didn’t deem that specific aspect of the API significant enough to include it in the official documentation. Still, other forum users were able to assist with home-brewed solutions.

API example on Unity
Source: Unity

Besides relying on the community, some companies also encourage the support staff to answer the forum questions.

Either way, this sort of unstructured content lets you cover uncommon scenarios while keeping the actual documents clean.

If you want to extend the service life of your support forum, you should make the knowledge base searchable.

That way, you’ll prevent an influx of identical queries and provide the users with tried-and-true solutions.

Take a look at what one thankful Unity user said about the SceneView answer that we’ve just seen, three years after the answer was posted.

One Unity user said about the SceneView
Source: Unity

So, where there’s no room to elaborate an API aspect in official documents, support forums can fill in the gaps.

An additional benefit of support forums is that they can decrease the number of support tickets you receive, lowering your operational costs.

Instead of contacting support and waiting, users with issues can first check the support forum and find the solution already there.

After all, 90% of customers want an immediate response when they have a support question, so a support forum could keep you in your users’ good graces.

However, for best results, you should keep in mind the public nature of forums. Moderating the content will ensure that answers provided by the community members are relevant and helpful.

You can improve the user experience by periodically reviewing the content, flagging incorrect or inappropriate responses, and verifying the best answers.

API Marketing Materials

With so much effort you’ve put into creating quality API documentation, it would be a shame not to use your API for promotional purposes.

You can supplement the documents with API marketing materials.

These cover various types of content you produce to advertise your API, such as tutorials, press releases, infographics, and even social media posts.

Polishing your API references and code examples is certainly an excellent way to assure developers of your software product’s quality.

Doesn’t a neatly organized reference guide, like the Notion’s one that you see below, inspire confidence in the company?

Introduction in Notion
Source: Notion

Still, it’s worth noting that the decisions about purchasing software solutions are rarely made by a single person, so it isn’t sufficient to wow a developer with attractively described endpoints.

Instead, it’s usually a team of people in both non-technical and technical roles that makes purchasing decisions.

That’s why your API marketing materials need to appeal to audiences of different backgrounds.

Notion, the company whose reference guide we’ve just mentioned, knows the value of API marketing materials. They even run a Twitter account designated solely to the product’s API!

Notion API Twitter
Source: Twitter

Unlike other types of API documentation, the purpose of marketing materials is to appeal to developers, product managers, and even end-users.

If you observe how Notion advertises the API, you’ll notice that they use plenty of visually appealing illustrations and plain language in their communication with customers.

The strategy extends further than Twitter; Notion also publishes release notes that reflect the constant improvements to the API.

API, integration and link previews on Notion
Source: Notion

Creating convincing supportive materials for your API requires additional effort, but you can streamline the process by employing a team of technical writers, designers, and copywriting experts.

We recommend to read: Why SaaS Startups Need Technical Writers.

We know; the people working directly with your API are probably more interested in error responses.

Still, investing in good marketing materials will help you attract more clients that will appreciate your actual API documents and put your product to good use.

Conclusion

Luckily for you, you don’t have to limit your API documentation to only one document type.

In fact, it might be better to combine all of them to ensure that no part of the API is left undocumented.

Whatever API document type you decide to create next, always remember to make the documentation informative, concise, and navigable. Archbee can help you with that!

That way, you’ll help developers use the API to its maximum capacity and grant your product many positive reviews.

FAQ

Frequently Asked Questions

What is the importance of API documentation?
Expand FAQ

There are several types of API documentation that you should be aware of: code recipes and examples, in-depth topical guides, reference guides‌‌, support forums‌‌, API marketing materials.

API documentation is crucial as it provides developers with detailed information on how to effectively use and integrate an API. Good documentation not only makes the users' lives easier, but also makes the software more appealing to new customers.
What is the role of code examples in API documentation?
Expand Button

Luckily, you don’t have to limit your API documentation to only one document type. In fact, it might be better to combine all of them to ensure that no part of the API is left undocumented.

Code examples in API documentation serve as guides for developers, letting them test the API and see its performance. They can be modified and tweaked as needed, making them more user-friendly and accessible. Examples also often contain copy-pastable code to make the developer's work more efficient.
What is the purpose of in-depth topical guides in API documentation?
Expand Button
In-depth topical guides in API documentation provide detailed explanations about the API's specialized areas. They portray the ideas and conceptual aspects behind the API and its design, helping to convince high-level customers about the quality of the API.
How are reference guides used in API documentation?
Expand Button
Reference guides are a clear-cut type of API documentation that provide details about method, classes, functions, parameters, return types, arguments, and properties. Despite containing crucial data for API use, they shouldn't be used as a substitute for complete API documentation.
What role do support forums play in API documentation?
Expand Button
Support forums serve as platforms where users can discuss and solve issues encountered with the API. This allows for coverage of edge-cases without cluttering the primary documents. These forums can decrease the number of support tickets, reduce operational costs, and improve user experiences.

📖 Table of contents

Answer questions instantly

Create and share documentation that answers questions instantly with Gen AI

Discover Archbee

Receive documentation and technical writing tips & trends — our newsletter

Join 5000+ people from around the world that receive a monthly edition of the Archbee Blog Newsletter.

Read more in

Documentation