A platform exposes APIs to internal teams. How should these differ from APIs exposed to external customers?
Show the full answer Hide the answer
What is genuinely different
You can see and influence your consumers. With external customers you cannot enumerate them; internally you can, which changes the deprecation calculus fundamentally — a breaking change is negotiable with named teams on a known timeline rather than an unbounded broadcast.
Migration can be done for them. The platform team can open the change against each consumer, which is not available externally.
Coupling is acceptable in places it would not be externally, because both sides deploy in the same estate and coordination is possible where necessary.
What must be the same
Backward compatibility discipline. Internal consumers are as broken by a breaking change as external ones, and a platform that breaks its users loses them permanently — after which they build their own and never return. This is the mistake most often made on the assumption that internal means informal.
A deprecation policy with real dates, communicated ahead, with usage measured per consumer so the conversation is with named teams rather than a guess.
Documented guarantees, not just endpoints — consistency semantics, rate limits, failure behaviour, idempotency. Every guarantee left unstated is one a consumer will assume, usually the strongest one.
Published SLOs, because a consuming team taking a dependency needs to know what it is depending on.
The property internal platforms most often lack
Usage telemetry per consumer and per endpoint. Without it, deprecation is guesswork, capacity planning is guesswork, and the platform cannot tell which of its capabilities matter.
It is also the raw material for the most valuable conversation a platform team has: "three teams use this, here they are, here is their migration path" — which converts a political problem into a task list.
The failure to avoid
Treating internal APIs as changeable at will. The visibility advantage is real and it is not a licence; it shortens the deprecation timeline rather than removing the obligation.