Documenting Your API Around Its Capabilities
How can consumers know what your API does if you're not showing its capabilities?
The most important thing about APIs is not their operations. At least, not for potential API consumers. The thing they value the most is understanding what capabilities an API offers. And, by capabilities, I mean the things that make people's lives easier. "Each benefit that users reveal can map directly to one capability. You work backward from the benefit to how your API would help users realize it," I wrote in 2024 in Building an API Product. If understanding capabilities is so important in API discovery, how can you document them easily? Let's find out.
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.
Most people don't care about a product's features. What they care about is how they can benefit from using it. It makes sense if you think about it. When you're comparing products, you're thinking about how well they adjust to the outcome you want to achieve, not their particular ways of operating. Something similar happens with APIs. Operations, HTTP methods, parameters, and payloads don't matter as much as capabilities do. Because capabilities are connected to business-related outcomes, it's natural that any decision to use your API involves understanding what its capabilities are. In other, perhaps simpler to understand, words, capabilities are the translation of what your API does to business folks. In that case, why aren't API providers documenting capabilities better?
There's a mismatch between what API providers think their audience is and who the decision-makers really are. While providers publish their documentation targeting developers, the API decision-makers are less technical and more business-savvy. Developers care about operations, HTTP methods, parameters, and payloads. And that is why API documentation focuses mainly on those technical aspects. How do I know that API decision-makers are less technical than developers? Well, according to the Postman's 2024 State of the API Report, around 30% of API users aren't developers. Additionally, the same survey shows that 40% of respondents follow business-related directives when developing their APIs and integrating with existing ones. These findings are consistent with other industry reports like Treblle's Anatomy of an API 2024, which shows that more than half of companies using APIs are not in the IT industry. These, along with the growing usage of AI as a primary API consumer, give us a landscape primarily dominated by non-technical decision-makers. And the tendency is that this dominance will grow over time. In this scenario, it doesn't make a lot of sense to target your API documentation exclusively at developers. It's definitely time to write it in a way that your non-technical stakeholders understand. So, how can you document your API capabilities?
Identifying capabilities is an exercise that begins with understanding the benefits your API offers to consumers. Benefits are the things that consumers obtain after they use your API, not what your API has to offer. You need to understand how consumers use your API and what their daily habits are. A good framework is studying your consumers' jobs-to-be-done (JTBD). Each JTBD represents something one or more consumers are trying to accomplish by using your API. After you group JTBDs by categories according to their similarity, you'll notice that clusters of benefits begin to emerge. If you then order those clusters by degree of criticality, you end up with a list of the most important benefits your API offers to potential consumers. I think you can already see where this is leading. With the list of benefits, you can get to a list of API capabilities by translating each one. While the benefit is what consumers achieve, the capability is what helps them get there. Let's look at an example to make things easier.
Suppose your target consumers are looking for a solution to help them easily manage their monthly income and expenses. Their short list of JTBDs would look something like this:
Track and categorize expenses in real time.
Get alerted before overspending a budget category.
See a clear monthly summary of income vs. expenses.
Converting these JTBDs into benefits would look like this:
Gain instant visibility into your spending habits with real-time transaction categorization.
Stay within budget with automatic alerts when they're about to overspend.
Get a clean monthly summary of income vs. spending, ready to display or email.
And, finally, these are the API capabilities that you get from translating the benefits:
Transaction enrichment: submit raw financial data and receive cleaned, structured, and categorized transaction records in real time.
Budget monitoring and alerting: define budgets for spending categories, monitor progress toward limits, and trigger alerts when you approach or exceed thresholds.
Financial reporting and summarization: generate structured summaries and visual-ready breakdowns of income, expenses, and net savings over time.
With these examples, it feels much easier to understand how API capabilities work. Documenting them should now feel like expanding each definition and explaining it would help consumers get their jobs done. Expanding means connecting the capability definition to one or more API features. Documenting the first API capability would involve fully explaining what "Transaction enrichment" is, showcasing a few use cases for your target audience, documenting the API operation along with its path, method, any parameters, and request and response payloads, and finally, the ability to offer a mock API operation for the capability.
Overall, documenting API capabilities means that consumers understand the whole picture for each operation. Consumers start by reading about the use cases that matter the most to them and associate them with the corresponding API operations. In other words, documenting your API around its capabilities means that you walk backwards from the operations to the JTBDs and the benefits they offer to consumers.