Referencing a Tutorial for Each OpenAPI Operation
The best place to teach people is where they go to learn.
People don't like to follow instructions. At least that's what the authors of the "Life Is Too Short to RTFM" academic paper concluded. According to the text, "manuals are not read by the majority of people, and most do not use all the features of the products that they own and use regularly." But, to those who like to read, the manuals need to be worth their while. In the world of APIs, a common entry point into the "manual" is the reference. In many cases, the reference is automatically generated from an OpenAPI document. Consumers then browse the reference searching for the operation they're interested in. And when they find it, they want to try to use it. Wouldn't it be great if they could easily access a tutorial while accessing the reference for each operation? Follow me to know more.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
Learning by doing is much better than simply using a reference manual. When I was in university, I loved the electronics laboratory classes. They complemented the more theoretical lectures and were a way to see how things really worked. Even some of the popular electronics books at the time offered lots of practical information, not just theory. Looking back, it's interesting to see how books like the ARRL Handbook or The Art of Electronics were filled with examples to illustrate the concepts being shared. The "from zener to series-pass linear regulator" section from The Art of Electronics reminds me of what a great tutorial is. It's written in such a way that you can take it directly to a laboratory and follow it to learn how regulators work. And, seeing how things work is crucial in electronics as it is in other subjects, where interactivity is a key feature. One such subject is, not surprisingly, APIs.
Trying isn't about understanding the capabilities of the API; it's about seeing how they work. While trying, consumers can feel what they can do with the API. But trying without guidance leaves you in a situation where you get demotivated if you can't get the results you're looking for. And that's where a tutor would come in. Someone available and willing to spend time showing you how things get done. Guiding you through the steps needed to get things done. Advising you on what the best approaches to get things done are. Unfortunately, we can't all have access to a tutor for each existing API operation. So, instead, we get the next best thing: a tutorial.
Tutorials are lessons where readers follow a set of steps to learn how to use one or more API operations. The goal of a tutorial isn't to teach you how to do a specific thing. No, that's the role of how-tos. The goal of a tutorial isn't to give you a shortcut to an otherwise complicated process. No, that's the role of quick-starts. A tutorial would be something like "Accept a payment," in the case of Stripe, or "Push Data to Algolia." Tutorials have certain elements that make them especially user-friendly and easy to follow. So, just to name a few of those elements, readers should be able to follow a tutorial safely and in a user-friendly way. To do that, it's essential to offer an API sandbox, give users the choice of the programming language they prefer, and show a clear path towards the goal of the tutorial, something easy to follow. All these elements need a place of their own. And that place isn't naturally the already cluttered API reference.
Going back to how we started, let's see how we can give our API users an easy way to find the tutorials they're looking for. One easy way is to add a link to a tutorial in the description of each operation. Yes, that can be a simple option. However, it's not easy to maintain, and the way the link is shown in the reference isn't predictable. I mean, because it's part of a description, it can be rendered in different ways depending on the size of the description and the device the user is browsing from. Fortunately, there's an OpenAPI attribute that's been thought for adding links to external documentation on each operation. The attribute is called externalDocs and is an object with two properties: a description of the document you're linking to, and the url of the document. You can link external documentation from different OpenAPI elements, not just from operations. Here's a simple example of an operation with a link to a tutorial:
(...)
paths:
/users/{userId}:
get:
summary: Get a user by ID
description: Retrieve detailed information about a specific user.
operationId: getUserById
externalDocs:
description: Step-by-step tutorial on how to get information about a user.
url: https://example.com/docs/tutorials/get-user-by-id
(...)Now, whenever users open the reference getUserById, they'll see a link to a tutorial they can follow to learn how to use the operation. Even though this looks like a simple improvement to an API reference, it can have a big impact on the usability of the API.