Consider a service that must expose both internal APIs for other services and external APIs for clients. How would you structure versioning, validation, and error handling so that changes don’t break existing consumers?

Question

VirtualInterview.AI · Accepted Answer

I like to treat internal and external surfaces as related but distinct products. For external APIs, I’d use explicit, URI-based versioning like /api/v1 and treat them as strictly backward compatible; breaking changes always go to v2, and we deprecate v1 on a clear timeline with usage dashboards. Internally, I’m more flexible and prefer contract-first design with protobuf or OpenAPI plus consumer-driven contract tests, so we can evolve fields while staying compatible.

For validation, I push strict schema validation to the edge with clear, machine-readable error bodies (error codes, fields, human messages) and stable error taxonomies. Internally we can expose richer error details; externally we keep it minimal and predictable. I also add feature flags and shadow traffic for new versions, so we can validate behavior and roll out with essentially zero downtime or surprises for existing consumers.

Sample Answer

Keywords