Reading isn’t enough when you want to learn something new. To actually learn how to do something, you need to try it. Perhaps you’ll fail a few times, but that’s all part of the learning process. Figuring out how to use an API isn’t any different. You read the documentation, go through its reference, and then what you want is to try it, to use it, to see how it works. That’s when the friction usually begins. Many APIs, you see, don’t provide an easy way to try them. Not even an easy way to get authorization credentials. Or, even easier, a basic sandbox where you can play before signing up. As a developer, you have to copy a URL or a code snippet and paste it into your favorite API client or IDE. While this might sound simple, it’s an extra context switch that prevents a short TTFC (time to first call) and a stellar DX (developer experience). If this is happening to your API, please fix it and offer what I describe in this article.
This article is brought to you with the help of our supporter, Scalar.
Scalar is the modern OpenAPI platform for the entire API lifecycle. Govern APIs with Scalar Registry, test offline with their built-in Client, generate beautiful documentation, and ship SDKs instantly - all from your single source of truth.
So what’s really the problem? Can’t developers copy a curl snippet or a URL and some authorization parameters? Don’t they have an API client at hand? Most of them do. But that’s not really the point. The point is that making a developer leave your API documentation to be able to try making a request creates unnecessary friction. Too many things can go wrong. First, developers need to have access to an API client. Then, they need to copy a snippet if there’s one, or build a connection request by hand. Then, they need to actually make the request to the API just to be able to see if it will work. And all that happens outside of the API documentation. All that happens on an environment that you can’t control or influence. Because those two activities (reading the documentation and trying the API) happen in different locations and times, there’s no feedback loop that informs the API documentation page of the result of each request. When things don’t work, developers need to go back and forth between the documentation and the API client and make changes until there’s a fix. On top of that, there’s a high chance that the snippets you’re sharing get outdated. Among the many things that can break between changes are hardcoded example values like IDs and tokens, parameters that were renamed or turned from optional to required, and authorization instructions that stop making sense because the security scheme changed. The problem gets even worse if you offer snippets in multiple programming languages. In summary, the reference quickly gets outdated, and, even worse, there’s no simple way for developers to try the API.
Fortunately, there’s a solution to this situation. Stop treating documentation as a static document and start looking at it as a way to let users interact with your API. Let users make requests to your API from inside the documentation. This is the so-called “try it out” pattern that I bet many of you are familiar with. How does it work? Each operation on the API reference shows a button that lets you make a request to the API right from the browser. That’s the power of it. You don’t have to stop what you’re doing to try the API. How do you make that work? You have open-source and commercial options that are easy to set up. The goal is to get rid of those outdated code snippets and instead give users a way to try the API directly from the browser.
Let’s do just that then. The goal is to have an in-browser API client directly generated from the OpenAPI document. It doesn’t have to be a fully featured API client. However, it needs to do its job well and be easy to use. These are some of the things I would want:
Real-time schema validation: any parameters and the body payload get checked against the OpenAPI schema before the request is made.
Secure authorization handling: the documentation page can store an API key, perform an OAuth credentials exchange, or let users securely save any other authorization headers and parameters. No information is stored outside of the browser.
Live parsing of responses: after a request is made, the response is parsed and rendered directly on the documentation page. Rendering is different depending on the type of response, e.g., errors are treated differently.
Other things include live generation of code snippets in multiple languages, and even the ability to generate example request parameters and payloads to help users try the API. But these aren’t as important as the main things I shared before. What’s important is that having an API client directly in the reference page completely improves the experience of users who want to try the API. A side effect of having an in-page client is that it can’t ever go stale. Whatever is in the OpenAPI document is automatically reflected in both the API reference and also the client.
Will the in-browser client make direct requests to a production API? That’s just one of the questions you need to ask yourself. There are risks and hidden costs associated with making an API client available right on the reference pages. One thing you’ll have to spend time configuring is CORS, the cross-origin resource sharing mechanism that controls what requests can be made from the browser. By default, you can’t make direct requests from a browser to something that lives on a different domain, so keep that in mind before deploying your API client. Also, and depending on what environment your API is running in, you’ll want to rate-limit the requests coming from the browser to prevent potential abuse, since the API reference is openly accessible. Credential exposure, especially if you’re dealing with a production API, is something to pay attention to. Limiting requests to a sandbox removes that risk, but the environment might fall out of sync quickly. If you want users to be able to try the API even before they sign up, you have to make the flow work flawlessly. In summary, while setting up an in-browser API client might sound simple, maintaining it comes with its costs.
Whether you make an investment and go all-in on adding an API client to your reference page, or you stay as you were, is your choice. Not having a client and having to synchronize code snippets by hand isn’t free, but at least it doesn’t generate security risks. On the other hand, not having an interactive client on the reference pages makes potential new consumers give up before they even have the chance to see how the API works. Which is more expensive for your API: the friction of not letting users easily make their first request, or the operational costs of running an in-browser try-it-out API client? Answer this question, and you’ll know what to do.
Thanks for reading The API Changelog!
Please consider subscribing to receive new posts and support our work.
Not convinced yet? Get to know why we’re considered “the most important API newsletter out there.”

