Trying Is a Way to Learn How an API Works
What is better than reading API documentation? Can trying an API be a way to learn how it works?
Learning by trying is a shortcut to gaining quick knowledge about any topic. By experimenting, you're able to understand how something works. With APIs, being able to experiment is fundamental. Not because APIs are harder to understand than many other things. Not because APIs are difficult to document. It's because APIs are interactive, unlike other topics you can learn about. You can interact with an API and, by doing that, you learn how it works and what you can do with it. So, how does trying an API feel like? Keep reading.
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.
Using an API for the first time generates a feeling of excitement. The first time you make a request and see the response on the screen, it is tantalizing. You begin to understand how the API can actually become a tool you can use. You begin to imagine how you can integrate the API with your code. You even start imagining what the code would look like. All these feelings can't be replicated by a piece of static documentation. It's simply not possible to show how an API works just by explaining. I mean, you can share your view of how the API works. But you can't convey how it feels like to use the API.
In other words, trying an API is a natural extension to documentation. While documentation—and reference, in particular—provides a source of truth of what the API is capable of, trying offers a layer of experimentation. Trying isn't about understanding the capabilities of the API; it's about seeing how they work. While trying an API, you can understand how it can help you with your particular use case. You can try it using your own data and your own parameters. And see how it reacts. Immediately.
APIs that offer a way for users to try them are always better than the ones that don't. There are many ways you can give users the opportunity to try your API. To begin with, having a sandbox where users can play without the fear of breaking things is mandatory. Without a sandbox, trying can actually be dangerous, especially with APIs and operations that act on real data. You wouldn't like to try using a payments API only to find out it was actually using your credit card, would you? Or, what about trying a messaging API and seeing it sending thousands of messages to real people? These are things that can't happen while a user is trying an API.
With a sandbox at hand, users can make requests to your API in a safe way. That doesn't mean making a request is easy, though. Users still have to configure their API client, or worse, write code from scratch to connect with the API. Something that alleviates the process is offering ready-to-use code samples and even a full SDK. The goal is to shorten as much as possible the time it takes to try the API. Stripe, for example, offers a quick way to try their API with different programming languages. They do that by offering a sandbox via what they call a "public sample test mode API key." You can make API requests immediately without even having to sign up.
What's more interesting to me is having the ability to try the API right from the Web browser. This approach can take different shapes. Some APIs offer a button that lets you open an API client directly on the browser. Maersk, for instance, has a button labeled "Test request," while Intercom's button is called "Try it." However, both open a browser-based API client when clicked. It's a clever solution because it gives you the possibility of experimenting the request in a complete way. You can tweak any parameters—even adding ones that were not contemplated in the reference—as well as headers and any other input elements. You can then see how the operation behaves as you change your input.
Another solution I enjoy using is the one that Google uses on its Ads API. Instead of opening a full browser-based API client, it shows a form right next to the reference. While it's true that the form isn't as flexible as a full API client would, it gives you enough room to see how the operation behaves instantly. What I like about this approach is that it's easier to understand and use compared to the full API client.
In conclusion, offering a way to try your API is a way to attract potential consumers. It's undeniable that most people like to try things before committing. Whether you offer just a sandbox environment, a full browser-based API client, or simply a request form, you're giving users the ability to see how your API works. And, in the end, that's what really matters.