The same `GET /orders/{id}` endpoint means three different things depending on who's calling it, and most teams design it as if only one caller exists. An internal service calling it might reasonably expect the full customer record, including fields nobody outside the company should see, because the caller is a trusted colleague's code running inside the same security perimeter. A partner's billing-reconciliation integration calling the identical path needs a stable, versioned, rate-limited contract it can build a business process against for years. A public developer building a hobby project against the same path needs to be told, unambiguously and in advance, what it's allowed to depend on — because you will never get to negotiate a breaking change with them directly. One endpoint, three audiences, three completely different sets of promises, and treating them as one problem is where this gets expensive.
Most teams don't consciously decide to serve all three tiers with the same API — it happens by accretion. An internal service gets built quickly with minimal ceremony because both ends are the same team. A partner integration shows up because sales closed a deal and the fastest path was pointing the partner at the internal API that already existed. A mobile app calls straight into what the backend team still thinks of as an internal service, because building a separate public-facing layer felt like unnecessary overhead at the time. None of these decisions looks wrong in isolation. Collectively, they leave an API serving three audiences with the assumptions and safeguards appropriate to only the first one.
What breaks without deliberately separating these tiers is predictable: internal debugging conveniences — verbose stack traces, unfiltered internal IDs, permissive error detail — leak to consumers who should never see them, and consumers who need contractual stability get none, because the API still evolves at the internal team's pace with no notice. This lesson is about naming the audience explicitly before designing the contract, not after a partner's integration breaks in production because someone renamed an internal field on a Tuesday.
Analogy🏏Cricket
🏏 Think of it like cricket: A franchise's training ground has three genuinely different populations moving through it in the same week, and the ground staff treat each one completely differently even though all three are, technically, 'people walking onto the same practice pitch.' The squad's own players and coaching staff walk onto the main practice pitch whenever they need to, with no booking process, because they're inside the organization and a coach can just tell a bowler to bowl an extra ten minutes without filing anything. A commercial partner — say, a bat sponsor running a promotional net session with a handful of client's guests — gets a specific, pre-arranged slot on a side net, with a liaison staff member present the whole time, because the arrangement is contractual and both sides need it to go exactly as agreed. A member of the public who's won a stadium-tour ticket gets nowhere near an actual practice pitch at all — they see a viewing gallery, roped off, with a guide narrating from a safe distance, because the ground has no ongoing relationship with that visitor and no way to vet what they might do once inside. Just as the same physical ground offers three completely different levels of access depending on who's asking and what relationship exists, the same backend logic should offer three completely different contracts depending on whether the caller is your own team, a contracted partner, or an anonymous public consumer. Just as letting a tour visitor wander onto the actual practice pitch unsupervised would be an obvious lapse regardless of how harmless most visitors are, exposing your internal API's raw shape to public consumers is a lapse regardless of how well-behaved most of them turn out to be. The insight is that access tier isn't a property of the physical space or the underlying logic at all — it's a property of the relationship with whoever's asking, and that relationship has to be decided before anyone walks through the gate, not improvised once they're already inside.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.