APIs Aren't Pipes (and That's a Good Thing)

I was recently asked to weigh in on a subject theoretically within my wheelhouse. What the actual subject was is irrelevant, however, as I couldn't get past the framing of the question. Their question started with, "Since APIs are just data pipes-"

Record scratch. The Windows' "doink" sound. Homer yelling 'Doh!'. I couldn't even process the remainder of what was being said.

The person speaking wasn't being malicious. They were simply repeating a line that is often repeated in far too many conversations about APIs. When it comes to technical complexity, particularly abstractions like APIs, people latch onto language that is simple and intuitive. Pipes are a logical model for APIs. They are something you build and connect. They transfer something from point A to point B. Pipes have a throughput. They are part of a building's architecture. Sometimes, they break and need to be replaced. 

"The internet is a series of tubes!"
- Senator Ted Stevens, 2006 

But APIs aren't pipes. And the more we keep pretending they are, the more strategic opportunities we bury under layers of semantic misdirection. 

This mental model doesn't just make our discussions harder. It makes the resulting APIs worse. Perpetuating the "APIs are data pipes" metaphor quietly shapes how people think about API investment, design, and purpose for the worse. 

If API practitioners are to garner the kind of budget and support necessary to have sustained, impactful success, then we need to correct a bad frame of reference.

When data rules your interface designs

The "just pipes" framing appears in tech writing, vendor decks, onboarding docs, and even strategic planning conversations. 

Several years ago, as the lead for a Fortune 500 company's API CoE, I was plugged into our burgeoning AI effort. Like many others, we were racing to transform our "big data" into "actionable LLMs" and found we had less of a data lake and more of a data dumping ground. Naturally, the data scientists were leading the effort. 

Also, unsurprisingly, they assumed APIs were merely plumbing responsible for transferring data between systems. From the data stakeholders' perspective, the role of APIs was straightforward: expose the data so that LLM could be trained on it. They were dismayed that an API design might not expose every field in the database. They were confused as to why a field named some unpronounceable legacy jargon, like "LX90fieldfirst" had a more intuitive abstraction in the human-facing design they now needed to map. Sometimes, an API would apply policy logic, much to their chagrin, like only returning data that the authenticated user is authorized to see. To those holding the "APIs as pipes" mental model, these design matters seemed like unnecessary complexity.

What that framing prevented them from seeing is that the abstraction was the value.

To someone trained to think of data as something to extract and analyze in bulk, those shaping decisions can seem like friction. However, for teams building services, integrating workflows, or consuming the API as part of a real-time application, those design decisions are what make the data usable.

But the data team was in the driver's seat, and several APIs were modified or created whole cloth under their direction. The results were APIs that were:

• Tightly coupled to volatile backend schemas, which meant any database refactor rippled outward.
• Lacking abstraction, forcing every consuming system to implement their own hacks and workarounds.
• Designed for internal convenience, not external understanding, resilience, or reuse. 

With this approach, the AI model-making effort struggled, not because the data wasn't accessible, but because it was unusable. The APIs passed too much, too messily, without a functional abstraction layer protecting each side of the transaction from necessary, underlying changes.

And I've seen this pattern repeat, not just in AI but also beyond. When people model APIs as passive infrastructure, they inadvertently kneecap their organization's ability to scale and innovate. 

So why do people hold onto this metaphor in the first place? 

Mental Models Are A Shortcut That Can Be Abused

Software is invisible. You can't hold it in your hands or point to it on a shelf. It lives in layers of abstraction, encompassing behaviors, logic, and compute. And because we can't "see" it, we rely on language to describe it.

We reach for metaphors not because we're imprecise but because humans are pattern matching machines. A metaphor offers a mental model to match against when the work itself can't directly be comprehended with our senses. We talk about stacks, engines, containers, pipelines. We invoke "glue code," "deadlocks," and "architectures." These aren't just terms; they're survival skills. They help us reason about the abstract, complex, and/or emerging. And most of the time, they're harmless enough.

But when a metaphor is limiting, it doesn't just fail to illuminate - it can actively misdirect.

On the surface, "APIs are data pipes" is tidy. Pipes connect things. They move stuff. They can be measured by throughput. They are infrastructure, not design. And, perhaps most problematically, they suggest that the API has no purpose other than to carry something, not to shape it.

If you're a harried executive operating under the assumption that APIs are "just pipes," you might assume:

• You don't need designers. Just engineers.
• You don't need product owners. Just a JSON structure.
• You don't need to plan for abstraction. Just expose what's already in the database.
• You don't need to budget for governance or lifecycle. Just keep the pipes unclogged.

This isn't a language quirk. This is a budgeting rationalization. After all, if APIs are pipes, there's no reason to budget for product management, design, or support. That money is better spent on throughput and uptime.

That's why the metaphor matters - because the mental model also shapes our decision-making.

We've seen this in other domains far beyond tech. In politics, for instance, metaphor use is highly strategic:

• Call a tax cut a "billionaire subsidy," and you imply theft from the commons. Call it "relief," and you imply a righteous return of fairness.
• Describe a hospital's end-of-life planning program as "compassionate care," and who would argue with that? Call it a "death panel," and it's dystopian.
• Call a regulation a "safety net," and people want to strengthen it. Call it "bureaucratic overreach," and people want to burn it down.

Language doesn't just reflect worldview; it shapes it. And nowhere is that more true than in organizations deciding what to prioritize. And that's why "just pipes" is so insidious. It obscures the path necessary for winning execution in pursuit of an over-simplistic shortcut.

If not pipes, then what? 

To be fair, API metaphors are difficult. There have been several that have come and gone in the past couple decades. Plenty of slideware still refers to APIs like Lego bricks because of their modularity and ability to snap together to create new experiences. Others have said that APIs are UIs for machines, emphasizing the interface aspect. At Gluecon circa 2013 or 2014, in response to the ongoing Google v Oracle API trials, I advocated for the use of the "APIs are menus" metaphor; I hoped to illustrate how it was OK for different kitchens to provide unique experiences (i.e., "Whopper" versus "Big Mac") for the same interface selection (i.e., "a hamburger"). 

These metaphors are fine as an introduction to APIs, but problems emerge if they are clung to too tightly. We need better metaphors, not just to explain APIs but to properly advocate for them. We need metaphors that:

• Expand imagination, not narrow it. 
• Position APIs as leverage, not labor. 
• And most importantly, connect APIs to how a company competes and wins. 

No metaphor is perfect. However, there are alternatives I continue to noodle with.

The Storefront

APIs themselves, not just their catalogs or portal pages, are like storefronts. They are a curated, discoverable, customer-facing entrance to your capabilities. Like a storefront:

• You choose what to put in the window.
• You design the experience.
• You don't expose the warehouse layout. 
• You monitor foot traffic and optimize for conversion. 

This framing highlights an API's intentionality - what's presented, how it's accessed, and who it's for. It resonates with product and marketing leadership who understand that what's visible and accessible drives increased consumption.

The Contract

We might also say that APIs are contracts. They define mutual expectations between producers and consumers. Like legal contracts, APIs:

• Specify terms (both on how to access as well as allowed behavior within)
• Are versioned.
• Can be breached.
• Outline accountability.

This metaphor works well in governance and risk discussions. It helps organizations think about APIs not as technical infrastructure or project architecture but as formal agreements that structure interactions between parties.

The Translator

APIs are translators. They sit between internal systems and external contexts, shaping internal complexity into something grokable and useful. They don't just repeat echo information; they contextualize it for the audience.

This would have been handy language to have in my back pocket when debating with those data teams years ago. This line asserts that clarity and interpretation are not overhead but essential.

Again, none of these metaphors are silver bullets. However, each of these metaphors presents different frames that get closer to the strategic need: explaining why APIs matter to businesses, illustrating what success looks like, and alluding to who benefits and how. 

How to push back on the pipe frame

Of course, you're not always going to be the one in charge of framing. Like the situation that kicked off this post, someone is going to tap you on the shoulder and say it. Or it will appear in a requirements doc, slide, or RFP - 

"-just pipe the data through the API."

At that moment, you have a choice. You can let the metaphor slide and allow it to set the tone for design, scope, and budget. Alternatively, you can gently and tactfully push back. 

Here are a few practical ways that I've found to do it.

🛑Reframe the Assumption

"That framing assumes the backend is correct, stable, and built for this use case. Is that actually true?"

This invites the group to recognize that backend systems are often legacy, inconsistent, or misaligned with today's product needs. The API is the layer where that reality can be shaped, not just exposed. 

🎯Refocus on the Interface

"Let's talk about the experience we want the consumer to have, and then we can figure out what data supports that."

This shifts the conversation from inside-out (data-first) to outside-in (user-first), reminding the team that APIs are interfaces, not just access points. 

🌱Invite Strategic Imagination

"If we weren't bound by the current database structure (or legacy system), what would the ideal interface look like?"

This question opens space for abstraction. It encourages design thinking and positions the API as a leverage point, not a limitation.

💸Connect to Business Outcomes

"This isn't just about moving data. What are we trying to enable? What's the business outcome we want to support?"

When executives are present, this is the anchor. It brings the conversation back to goals such as efficiency, composability, and time-to-market - not just bandwidth.

Bonus: Name the Metaphor, Then Replace It

"Pipes move stuff, but interfaces shape experience. If we treat this like plumbing, we'll miss the chance to design something reusable, understandable, and resilient."

Call out the metaphor directly and offer a better one. You don't have to shower them in Shakespeare; just disrupt the autopilot long enough to shift the conversation. 

Ultimately, this isn't about being your company's resident word cop. It's about reclaiming the narrative. Because if the wrong narrative gets baked into the assumptions, so will the wrong design, the wrong priorities, and the wrong expectations.

Push back early. Push back gently. And push back with metaphors that work for you, not against you. 

Language Shapes the World Around Us

The words we use don't just reflect what we believe; they also shape it. They shape what we build, how we invest, and what kind of change we make possible. When we reach for metaphors, especially in technical domains, we're trying to make the abstract concrete. That's a good impulse. However, we must be cautious because the wrong metaphor can harden into unintended constraints.

"APIs are just pipes" isn't just incorrect. It's corrosive. It cheapens the interface. It dismisses the design. It erases the consumer. It hands the future to infrastructure when it should belong to experience. 

If you work in APIs as a designer, advocate, or even as a consumer, you're not just a technician; you're a strategist. And you have permission to push back when the framing is too small for the work at hand. 

Because APIs aren't plumbing. They're opportunity. And if we want to build systems that are more than the sum of their parts, we need to speak about them in ways that invite more than throughput.

Milestones

• New Conference Alert! AI The Docs is an online, two-day event from the API The Docs team. It is happening this June 24th and 25th. I'm going to try and make time for this one.
• Did you like last month's API TTRPG? Well, turns out so did Tyk's Leonid Bugaev- so much so he and his team went and coded up an online, playable version. Check it out; it should be good for a chuckle (or maybe some tears).
• I'm always up for a microservice joke at DHH's expense.  
• Window's recall continues to roll out, screenshotting everything every few seconds so that an AI can interpolate if you have too many browser tabs open (or something). Signal, whose brand is privacy, cleverly invoked the Windows API for copyrighted materials to block this screenshotting behavior. I'll concede this isn't a web API thing. However, the hack was so clever that I had to share it.
• The end of an era is upon us, as Travis Spencer is no longer with Curity. While our paths have crossed less frequently than I'd have liked over the years (that's completely on me and my current 'recluse' era), I always found Travis incredibly considerate, polite, and one of the few people I'd refer to as erudite unironically. I wish him the absolute best in whatever he chooses to do next.

Wrapping Up

That's enough for now. Thank you for reading this far. Your continued comments, both here and on LinkedIn, Slack, and Mastodon, are appreciated. Like what you see? Tell a friend. And if you're not subscribed, sign up! Or don't. I'm not the boss of you. 

I'll catch you again soon in the next edition.

Till then,

Matthew (@matthew in the fediverse and matthewreinbold.com on the web)