Public API design versus internal API design

WHAT THIS TESTS The interviewer wants you to internalize that a public API is a promise to people you will never meet and cannot redeploy. That single fact reshapes versioning, authentication, and documentation compared to an internal API where you control every caller.

A GOOD ANSWER COVERS Versioning: a public API must version explicitly and never break a published contract, because you cannot coordinate upgrades with anonymous third parties. Deprecation windows are long, often a year or more, with clear communication. Internally, you control all callers, so you can change in lockstep, use lighter versioning, and deprecate fast. Authentication: public callers are untrusted, so you need strong auth, API keys or OAuth with scoped permissions, per-key rate limiting, quotas, and abuse protection. Internal services can lean on network trust, mutual TLS, or service identity with lighter ceremony. Documentation: a public API lives or dies by self-serve docs, an OpenAPI spec, quickstarts, SDKs, and a sandbox, because there is no one for an external developer to ask. Internal docs can be leaner since teammates can ask directly and read the source.

COMMON WRONG ANSWERS Applying the same change-it-whenever mindset to both, breaking external integrations. Skimping on public auth and rate limiting. Assuming internal-quality docs suffice for an external ecosystem.

LIKELY FOLLOW-UPS Why can you not just version an internal API the same way? What auth scopes would you expose publicly? What belongs in public docs that internal docs can omit?

ONE CONCRETE EXAMPLE For a public payments API you publish v1 with a stable contract, issue scoped API keys with per-key rate limits, and ship an OpenAPI spec plus a sandbox and SDKs so developers self-onboard. When you add a field you do it backward-compatibly and only break it in a v2 with a year of overlap. The equivalent internal API, called by three of your own services, you version informally and refactor freely in a coordinated deploy.