Lesson 3
The Three APIs You Will Actually Encounter
Fig 1.3 — Same capability, three different quality bars
Internal, partner, and public APIs are three different products with three different quality bars. Confusing them is how roadmaps get wrecked.
Internal API | Partner API | Public API | |
|---|---|---|---|
Who calls it | Your own engineering teams | A named set of contracted partners | Anyone with a developer account |
Documentation bar | "Good enough for the team that wrote it" | Must survive an outside engineer's first hour, unaided | Must survive thousands of strangers, unaided, forever |
How breaking changes are handled | A Slack message, a coordinated deploy | A contract clause, a migration window, an account manager's phone call | A deprecation policy, months of notice, a changelog nobody reads until it's too late |
Consequence of a bad decision | Slower internal dev, annoyed colleagues | A churned partner, a damaged relationship, sometimes a penalty clause | A public GitHub issue, a Hacker News post, silent abandonment by developers who never told you why they left |
Who "owns" the DX | Whoever's convenient | Usually a partnerships or platform PM | Almost always a dedicated Developer Experience or Platform PM |
The mistake I see constantly: a team builds something as an internal API — fast, a little inconsistent, documented in a wiki nobody outside the team reads — and then a sales deal or a strategic partnership means it gets exposed externally with basically no rework. Every shortcut taken because "it's just internal" becomes a partner's production dependency, permanently, because now someone else's business runs on the exact quirks you never intended to keep.
THE QUESTION THAT SHOULD BE ASKED BEFORE ANY API IS BUILT
"Who is this for, today, and who is it realistically for in eighteen months?" If the honest answer includes "maybe external partners eventually," design at partner-grade quality from day one. Retrofitting API quality after external dependencies exist is dramatically more expensive than building it in from the start — you're not just changing code, you're renegotiating a contract you didn't know you'd already made.
YOUR MOVE THIS WEEK
Take one API on your roadmap. Classify it: internal, partner, or public — honestly, including where it's likely headed. If it's currently being built to internal-grade quality but has any realistic path to partner or public exposure, flag that gap to your team this week, not after the first external dependency exists.