Concrete vs. Abstract API Examples
Concrete vs. Abstract API Examples
Both types of API examples have their utility and differences regarding their implementation
API examples are what make documentation come alive. Look around at the documentation of the APIs you use and you'll see examples in action. Most providers use examples as a way to show users what their APIs can do in a way that relates to real-life situations. But what makes an API example good?
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.
According to Daniele Procida, author of the Diataxis documentation framework, "examples are valuable ways of providing illustration that helps readers understand reference." James Yu, founder of Sudowrite, adds that examples "dramatically reduce the time for developers to understand your product." In fact, most documentation readers are looking for an easy way to answer their questions. And an example is often what does that job.
Examples are often used in API references to illustrate how an input or output would look like. However, you can also see examples in other parts of API documentation. API reference examples provide a quick way to understand how a request—and response—would look like in the real world. Because of that, examples that are a part of the reference can be translated into a mock server easily. If you're using OpenAPI you can even create multiple examples to provide a richer expression of how users can consume your API. The other places where examples have relevance are how-tos and tutorials. In the case of how-tos, examples are the threads that connect the different steps involved in reaching the goal. With tutorials, examples illustrate the topic you're inviting readers to explore.
Crafting good examples to show readers what they can do with your API might not be easy. Some people prefer examples that are concrete while others find more value in abstract ones. However, concrete examples might not be understandable by all consumers. On the other hand, abstract examples sometimes sound too vague to represent correctly what users need help with. Let's look at how both styles are different while trying to accomplish the same goal of educating API consumers.
Abstract API examples
You can consider an example "abstract" if it expresses nonrealistic, or made-up information. Abstract examples are simply created with the goal of showing how API operations can be used and not necessarily how they'll be consumed in a real situation. Adding abstract examples to an API reference is something you can do relatively easily. Taking into account that abstract examples only need to illustrate the shape of your data, you can generate fake information for all the data types you want to support.
A popular approach you can follow is to use something like Faker. This tool is available for programming languages such as JavaScript, Ruby, and Python. With it, you can obtain data that looks real but it's not factual. In other words, the data you generate with Faker doesn't represent a real usage of your API. Imagine you want to create examples for an API operation that retrieves users' details. You can use Faker to generate personal information like a first and last name, an age, an email address, and a postal address. The Faker JavaScript version is so powerful that lets you generate data from more than 20 areas including animals, colors, dates, finance, locations, and text. By using this approach you can automate the creation of fake data and generate as many abstract examples as you need.
Now, creating abstract examples for a how-to or a tutorial is something totally different. While before you could simply automate the generation process, now you'll have to give more thought to the examples you create. Both how-tos and tutorials are documents that guide users through a series of steps to educate them on how to use your API. In both cases, you need to come up with examples of things users can do with your API. These examples can't be merely a list of fake data. They need to be elaborate and define plausible workflows that readers can feel engaged with. One possible solution is to study your audience and understand what their problems are. Then, craft your document by presenting a hypothetical scenario—the example—they can relate to.
While abstract examples give readers an initial perspective on how they can use your API, nothing is better than showing them how to use it in real situations. Read on to see how you can offer concrete examples to your API consumers.
Concrete API examples
Examples that are "concrete" are the ones that show real data or provide a way to interact with existing resources. The goal of concrete examples is to teach users how they can complete real, actual tasks. Creating concrete examples is, thus, more complicated than coming up with abstract ones. However, there are two ways you can accomplish this.
One way of offering real examples is to provide a sandbox where consumers can experiment with interacting with your API. The data available on the sandbox is real but can be easily wiped. More importantly, the data available on the sandbox comes from interactions driven by consumers. API users can use the sandbox to test all its operations knowing they can delete the data at any time. APIs that perform non-revokable operations can offer a simulated environment that feels like the real one. In this scenario, all information used in examples is grabbed directly from the user's account. For instance, a "user's detail" operation will show as an example the information from the consumer account.
The other option is to offer the same type of examples but with the real API. This time, the information can't be easily wiped, operations can't be undone, and everything is performing for real. Among other things, one interesting concrete example is related to authentication. By providing the real authentication information instead of a fake one you let consumers simply copy & paste the code they need to start interacting with your API. Stripe, for instance, does exactly this on their developer portal. If you're signed in you'll see your API keys ready for you to use.
Using concrete examples in how-tos and tutorials follows the same logic as above. Instead of writing a one-size-fits-all tutorial, you can show users the tutorials that matter the most to them. All the information consumers see throughout the tutorial comes from their accounts, using their real information. There's one specific how-to where offering concrete examples makes all the sense: onboarding. When new users start interacting with your API, it's best to show them real information so they can quickly see how things work.
There's however something that you need to be careful with. The information you share with users might also be seen by other, often non-authorized parties. Be careful about what you show on your screen and what you let users download. You can, for instance, truncate API keys, masking personal information, and obfuscating payment-related data. Anything you can do to preserve the privacy of the data you're showing on the screen is important.
Summary
You can use examples in both API references and other types of documentation such as how-tos and tutorials. Abstract examples are the ones where the data and the use cases are made up. The information looks real but doesn't relate to any factual scenario. On the other hand, concrete examples are taken from users' accounts and relate to real information. Both types of examples have their utility and differences regarding their implementation. Abstract API reference examples can be easily created using a tool like Faker. Concrete examples can be obtained by retrieving real user information. In terms of security, you should take care whenever using and displaying concrete examples so unauthorized parties don't gain access to sensitive data.