Moving from API Operations to Business Capabilities | by Bruno Pedro | May, 2026 | MediumSitemapOpen in appSign up<br>Sign in

Medium Logo

Get app<br>Write

Search

Sign up<br>Sign in

Moving from API Operations to Business Capabilities

Bruno Pedro

5 min read·<br>Just now

Listen

Share

How to organize your API operations into business assets.<br>More than half of large companies now manage more than 1,000 APIs¹. Yes, one thousand. And, if each API has, on average, 10 operations, you end up with an inventory that is almost impossible to manage. It becomes exhausting to understand what operations are useful, or even which ones solve the problem you need solutions for. Add to that the fact that most problems require not one but a sequence of operations. What you end up with is a situation where it’s easier to reimplement a solution than to reuse an existing one. Can this be fixed? Absolutely. Keep reading to learn how.

This article is brought to you with the help of our supporter, Naftiko .<br>Naftiko is a platform that helps organizations manage their technical assets as business capabilities. It provides a central space where teams can define and discover what their services can actually do. By moving the focus away from raw API operations, Naftiko helps engineering and product teams work better together.

Imagine you’re a product manager looking for a way to “process a refund.” If you’re in an environment where API sprawling is a reality, you’ll have a hard time. With thousands of operations to choose from, how do you know which ones will help you build a workflow to process refunds? You’d not be alone, though, because one in seven companies “describe their API programs as being out of control.”² Not being able to find the right API operations is only one side of the problem. The other side has to do with reusability. If teams can’t reuse existing operations, they’ll build their own and duplicate existing functionality. You’ll begin to see different flavors of the same functionality with slight variations, depending on the team that built them. Creating and maintaining workflows in an environment like this becomes an impossible task. Fixing it usually has a high cost if what you want is to eliminate duplication. What if I tell you there’s another, easier way to get to a solution?<br>Instead of trying to build more operations and workflows, think of the capabilities you need. “Process a refund” is a great example of a capability. It’s not tied to any particular technology or provider. It has a direct connection to a business outcome. And, most importantly, anyone can understand what it does. In essence, capabilities act as a way to map one or more API operations to business outcomes. If tomorrow you change your payment provider, the capability is still called “process a refund.” However, behind the scenes, it might be using different API operations than before. But that is completely abstracted away from the consumer. Something else you gain with this approach is that your APIs become AI-ready. Instead of having to navigate REST paths, AI agents can execute easy-to-understand capabilities if they have clear names and purposes. Overall, there’s a lot to gain in working with capabilities.<br>Press enter or click to view image in full size

Having capabilities sounds like a great idea. However, sometimes making them work isn’t as simple as you’d wish. Here are a couple of alternatives that vary in their level of technical difficulty. One of the options is to follow a facade, or wrapper pattern, where you aggregate several operations into one single API operation. You build a new, simplified interface that sits on top of existing operations. This option is appropriate for situations where a business capability requires a specific sequence of technical calls to be successful. So, for instance, the “process a refund” capability would be a wrapper to several low-level operations like authorization, finding information about a transaction, executing the monetary transfer, and communicating the result to the final user. The drawback of this approach is that changing the wrapper isn’t simple. Fortunately, there’s a more modern option that makes things easier. I’m sure you’ve seen it before. Instead of creating a wrapper, you can create a workflow using the low-level operations to expose the capability. You can do that with open-source solutions such as Arazzo, Naftiko³, and n8n, and also with commercial products like Zapier and Tray.io. There’s plenty of choice, as you can see. The goal with the workflow approach is to represent a capability in a declarative (and often visual) way. This works quite well with AI agents, which find a textual representation of a capability very easy to work with.<br>Creating capabilities from existing API operations is a necessary step, but it is not a simple task. One of the greatest difficulties is finding the right level of detail. If a capability is too broad, it becomes useless. If it is too granular,...