Producer-Oriented API Documentation
If API documentation is so important to consumers, how can it also help producers succeed?
Everybody agrees that documentation is a fundamental piece of any good API. Good documentation, it turns out, is something you can quantify. You can understand how each documentation element affects the perception consumers have about your API. Even if those consumers are machines. But, what about producers? What are the documentation elements that can help a producer offer a better API? Stay with me as I dig in.
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.
As an API producer, your goal is to create the best possible experience for consumers. Like with any other product, you'll have to make periodic changes to your API so it adapts to the new needs of consumers. One thing you want to do is measure the impact of each change after you introduce it. You also want to keep track of how much consumers use each one of the API operations, how many errors they get, and how often. You want to know how many support requests each operation is responsible for. And, who are the top consumers interacting with and complaining about each operation. You want to see all this information—and even more—in a single location, preferably close to your API documentation.
Normally, you don't visit your own API documentation that often, right? I mean, if you already know how your API works, why would you want to consult its documentation? Conversely, there's a place you visit—or should visit—very often, with information you care about your API. I assume you have an API dashboard where you can review metrics such as the ones I described earlier. Usually, the dashboard lives close to the API gateway, or somewhere where other company-wide observability tools reside. What I'm proposing here, in short, is that the API documentation can be the best place to present those metrics to you, the producer.
Being able to see the metrics you care about right near the documentation for each part of your API feels refreshing. You could, for instance, be looking at the reference of one operation and immediately see its usage trend, the error rate, the number of active consumers in the last hour, and so on. What's more, some of the information visible only to you could also be actionable. You could, for instance, open the pending support requests to see what the top complaints are. Or, you could immediately check why there's such a percentage of errors on one single operation.
While most information would be restricted to you, the producer, I argue that some things could even be openly shared with your API consumers. Imagine being a consumer and seeing a list of "popular" API operations right on the documentation. Or understanding if a certain operation is producing a high error rate. All these things could be easily available in the API documentation.
Implementing the changes I'm proposing doesn't have to be complicated. To begin with, you'd need a layer of authorization, which I guess you probably have unless your documentation is fully static. Then, you'd need to have some RBAC system (or something similar) in place so you can decide who to share certain information with. Grabbing the metrics you want to show depends on how you currently have them stored. If you're using something like New Relic or Grafana, you already have those metrics in a place that's easy to query. Altogether, this doesn't feel like a high-cost project, and its benefits could be impactful.