Why internal APIs deserve more rigour than external ones
I lead the strategy and delivery of products and systems that solve real problems, support commercial goals and scale across teams and markets. My work spans platform foundations, user-facing experiences, commercial tools and developer products, and I adapt my approach to the needs of each domain. I focus on maturing complex systems, improving the experience for both users and developers and strengthening the foundations that make products reliable, scalable and easy to build on. I care about clarity, good judgement and creating the processes and environments that help teams deliver consistent, long-term impact. My experience covers early-stage, scale-up and enterprise product environments, combining hands-on delivery with team leadership and award-winning work recognised across several innovation competitions.
Internal APIs are often treated as second-class citizens.
They're "just for us", easier to change, faster to iterate, more forgiving when they break.
External APIs, by contrast, get the full product treatment: documentation, versioning, deprecation policies.
That logic is backwards.
Internal APIs deserve more rigour, not less.
The reason is scale.
Internal APIs are used by multiple teams, often in ways that aren't centrally visible. An authentication API might power checkout, account settings, admin tools, and three mobile apps, each interpreting "session timeout" slightly differently.
A small change can ripple across products, services, and delivery timelines, quietly and repeatedly.
When internal APIs lack rigour, a few things happen:
Breaking changes are discovered late
Teams build defensive layers and workarounds
Coordination costs rise without anyone owning them
Teams duplicate logic rather than risk depending on unstable APIs
Unlike external APIs, internal consumers can't simply leave. They're trapped inside the system. They can't switch vendors, can't choose alternatives, can't even complain publicly.
That captive relationship makes poor experience more costly, not less.
Another difference is trust.
External APIs have explicit contracts because the cost of breaking them is obvious, customers leave, support tickets spike, reputation suffers.
Internal APIs often rely on informal trust: "Just ping me if something breaks." That trust erodes quickly when changes are unpredictable. And unlike external customers, internal teams can't leave, they just build around you.
Over time, what was meant to create leverage becomes a source of fragmentation.
Rigour doesn't mean bureaucracy.
It means being explicit about:
Contracts and expectations
Backward compatibility
How and when change happens
In my experience, the most effective internal APIs are boring by design. They change slowly, communicate clearly, and remove uncertainty for the teams that depend on them.
Boring isn't a failure of ambition. It's a feature that enables speed everywhere else.
That stability is what allows the rest of the organisation to move faster.
The hardest APIs to change are the ones everyone depends on.
Stability upstream creates speed downstream.