Interview prompt. A product team at a design platform of Canva's kind wants to expose an internal service as a public API. "It already has HTTP endpoints, so the work is mostly documentation." Take it from here.
Show the full answer Hide the answer
What the interviewer is testing
Whether you understand that a public API is a commitment, not an endpoint. The HTTP interface is perhaps a tenth of the work. The rest is everything that follows from the fact that you can no longer change it when you like, and that strangers will depend on behaviour you never intended to promise.
The clarifying questions that change the answer
- Who is the customer, and what do they build? An API with no named use case produces endpoints shaped like your database rather than like anyone's problem, and nobody adopts it.
- What is the compatibility commitment? How long will a version be supported, and what counts as a breaking change? These are the two numbers the whole decision rests on.
- What is the internal rate of change? A service refactored monthly cannot carry a stable public contract without an explicit translation layer, and that layer is a permanent cost.
- What happens at ten times the request rate, from clients who do not care about your capacity plan? Internal callers are polite because you can talk to them. External ones poll.
- Who answers the support request? A public API generates developer support, which is a staffed function, not a rota favour.
- What does the data boundary look like? Internal services routinely return more than the caller needs. In public that is a disclosure, and multi-tenancy assumptions that were safe internally have to be re-examined field by field.
A strong answer's arc
Enumerate what is actually being bought, and price it:
| Commitment | What it costs |
|---|---|
| Stable contract | a translation layer or a frozen internal design |
| Versioning and deprecation | a policy - a timetable - and the ability to run two versions |
| Rate limiting and quotas per client | capacity planning against adversarial use |
| Authentication for third parties | key management - scopes - rotation - revocation |
| Documentation and examples | tested, in CI, or they rot within two releases |
| Developer support | a staffed channel and a response-time expectation |
| Abuse handling | detection, and a process for suspending a client |
Then make the recommendation concrete: either commit properly, or publish it as an explicitly unstable preview with no compatibility promise, a small set of named design partners, and a stated date by which it either graduates or is withdrawn. The second option is a legitimate answer and it is usually the right one for a first attempt - what is not legitimate is a public API with an implicit promise nobody has priced.
Common weak answers
- "Add documentation and an API key." The plan under examination. It produces an API that cannot be changed and was never designed, which is the worst of both outcomes.
- "Use GraphQL and clients can take what they need." Changes the shape of the commitment, not its existence, and adds query-cost control as a new obligation.
- "We will version it when we need to." Versioning is a capability to build before you need it: the first breaking change arrives on the worst possible day.
What a strong answer adds
Hyrum's Law, stated plainly: with enough users, every observable behaviour of your system becomes something someone depends on - including the field order, the error text, the timing and the bugs. That is the reason the commitment is larger than the interface.
And one piece of organisational honesty: a public API transfers the cost of your internal change onto a roadmap you do not control. Whoever owns the service must agree to that before the first customer is onboarded, because after that the decision has been made for them permanently.
The decision rule to offer: commit properly only when there is a named customer and an owner who accepts a support commitment of at least 24 months; otherwise ship an explicitly unstable preview with a withdrawal date. And name the failure that follows from skipping this: the first breaking change, 18 months in, arrives as an outage for every integrator at once, with no versioning capability to fall back on and no deprecation channel to announce it through.