Contract Versioning

1. What exactly is Contract Versioning?

A Checkout service calls a Payments service, both ASP.NET Core apps, through Azure API Management.

Now the Payments team adds a new required field and deploys it. Checkout is still sending its old request shape, and every single request now gets rejected with a validation error.

One team's change breaks every caller that hasn't updated yet, all at once. That's exactly what contract versioning avoids.

2. How would you fix it in .NET/Azure?

Contract versioning lets old and new requests coexist: add the new field as optional, with a sensible default value, instead of required, so ASP.NET Core's model binding fills it in automatically when a request doesn't set it. Host the old and new versions of the endpoint side by side in Azure API Management, so a caller still sending the old shape keeps reaching a version that accepts it, and callers can update on their own schedule.

Use: Azure API Management (Versioning)

A new field should be something old callers can ignore, not something they're suddenly required to know about.

3. How can you visualize it in everyday terms?

A building adds a new side entrance to speed up busy mornings. Anyone who doesn't know about it yet still walks in through the same front door as always.

Nobody is locked out just because a new way in was added.

A new required field is like removing the front door the moment the side door opens. An optional field just adds the side door and leaves the front one alone.