.NET Architecture & System Design Interview Question #121

How should API and event contracts be versioned?

Microservices, API Gateway, Service Communication & Event-Driven Architecture Mid-Level Intermediate

Quick Interview Answer

Contracts should evolve in ways that minimize breaking existing consumers. Additive changes are generally easier to tolerate than removing or changing the meaning of existing fields.

Detailed Explanation

Contracts should evolve in ways that minimize breaking existing consumers. Additive changes are generally easier to tolerate than removing or changing the meaning of existing fields.

For breaking changes, use an explicit versioning or migration strategy and allow consumers time to move. Contract tests, schema validation, deprecation policies, and consumer visibility reduce upgrade risk.

Code Example

v1:
{ id, total }

compatible addition:
{ id, total, currency }

Breaking semantic changes
-> explicit migration/version strategy