It’s not uncommon to manage hundreds of APIs in a drive towards increasing interoperability. Surprisingly, it’s also not uncommon to see organizations track them by spreadsheet, In one case, I reviewed a client’s API strategy that was encapsulated in two tabs: Published and Other. That was it. That was the strategy. Organizations have embraced the idea that APIs are important… they’ve heard the Bezos mandate story, they know the open banking regulations are coming, they nod along when someone says “API economy.” But it’s difficult to take the next step.
The Plumbing Problem
Most enterprise APIs are built by developers, for developers. They exist to connect System A to System B. They’re plumbing. And like plumbing, nobody thinks about them until something leaks.
When the goals become more aspirational, when your digital strategy depends on exposing capabilities to partners, channels, or entirely new business models, plumbing won’t cut it. You need products.
I worked with a large logistics company that had invested heavily in microservices. They had decomposed a monolith, built clean service boundaries, deployed on containers. Solid engineering. Then a business partner asked to integrate with their shipment tracking capability. It took the team four months to expose it as an API that an external party could actually use. Four months, for a capability that already existed internally. The problem was that nobody had thought about the API as something a human being would need to discover, understand, evaluate, and adopt. Nobody had designed the experience.
From Plumbing to Product
What does it mean to treat an API as a product? It means asking questions that engineers don’t typically ask:
- Who is the consumer? Not which system. Which person, in which role, trying to solve which problem? A partner developer integrating shipment tracking has completely different needs than an internal mobile team building a customer app.
- What’s the onboarding experience? Can a developer go from discovery to first successful call in under an hour? Or do they need three meetings, an NDA, and pour through documentation that may or may not be accurate, if they can find it in the first place?
- What’s the lifecycle? APIs aren’t fire-and-forget. They need versioning, deprecation policies, and communication with consumers when things change. I’ve seen organizations break partner integrations with unannounced changes because nobody owned the relationship.
- What’s the value exchange? If your API enables a partner to build a business on your capability, that’s not charity. There’s a commercial model in there somewhere.
The Developer Experience Gap
Here’s where I see the biggest gap. Organizations will spend months on user experience research for a customer-facing app, creating personas and journey maps, conduct usability testing, and iterate. Then they’ll document their APIs in a Word document and call it done.
The developer who consumes your API is a user. And right now, for most enterprise APIs, that experience is terrible. The tooling to fix this has existed for years. OpenAPI specifications, Swagger UI for interactive documentation, and sandbox environments for testing. The technology to make APIs discoverable for self-service is mature and widely available. The gap isn’t tools. It’s treating the developer as a user worth designing for.
Good API product management borrows from the same design thinking toolkit we use for any product. Empathy for the consumer. Rapid prototyping of the interface. Feedback loops. Iteration. The difference is that the “interface” is a contract, not a screen.
I recently saw a team do something simple but effective. Before building their partner API, they wrote the documentation first. Not as an afterthought, but as the design artifact. They described the resources, the operations, the error handling, the getting-started guide… all before writing a line of code. Then they handed it to a developer at a partner firm and asked: “Would you build against this?” The feedback reshaped the API. Edge cases they hadn’t considered. Assumptions about authentication that didn’t match the partner’s infrastructure. A data model that made perfect sense internally but was opaque to an outsider. All caught before a single endpoint was coded.
Open Banking is Just the Beginning
Regulations like PSD2 in Europe are forcing financial institutions to open up their capabilities through APIs. Most banks are treating this as a compliance exercise. Build the minimum, check the box, move on. The ones that will win are the ones that see this as a product opportunity. The same shift is coming to healthcare, logistics, insurance, and government. The organizations that figure out how to build APIs that developers actually want to use will have a significant competitive advantage over those that merely comply.
Your API Catalog is your Product Catalog
If you’re building a digital business, your API catalog is becoming as important as your product catalog. Maybe more so. Your APIs define what capabilities you can offer, how quickly partners can integrate, and how composable your business is.
Back to the logistics organization, after we reframed their APIs as products, they assigned product owners, built a portal with self-service onboarding, and cut partner integration time from months to days. The technology barely changed. The mindset did.
So pull up your API spreadsheet. Look at those two tabs. Then ask yourself: if a developer landed on this for the first time, would they know what you do, why it matters, and how to get started? If the answer is no, you may want to consider a renovation to hide the plumbing behind the walls and install a nice vanity.
