How do you version a public API without breaking clients?
Reported in HelloFresh European engineering loops. API evolution question covering compatibility, deprecation, and communication.
Interview scenario
Often asked in HelloFresh loops at European offices (London, Berlin, Amsterdam, Paris, Stockholm, Dublin, and remote EU). Prepare a clear spoken answer plus key trade-offs.
Model answer
Try answering aloud first
Cover trade-offs, structure, and a concrete example before revealing the baseline response.
How to frame this at HelloFresh: Connect your answer to measurable impact, clarity of thought, and trade-offs the team cares about. Below is a strong baseline response you can adapt with your own project examples.
URL versioning (/v1/users) is explicit and easy to route—most common for public REST. Header versioning (Accept: application/vnd.company.v2+json) keeps URLs clean. Query param is rare for major versions.
Within a version, make backward-compatible changes: add optional fields, never remove/rename without new version. Use expand/feature flags for experimental endpoints.
Deprecation policy: announce timeline, sunset headers (Sunset, Deprecation), monitor usage metrics, and maintain N-1 version minimum. Breaking changes require new major version.
Document changelog; contract tests for consumers; consider GraphQL schema deprecation or protobuf field numbers for gRPC. Emphasize communication over clever breaking changes.
Discussion
Comments (0)
Share how this question came up in your loop, or add tips for others preparing.
Log in to comment on this question.