What's the difference between versioning a REST API's contract versus versioning its underlying data model, and why does that distinction matter?

API contract versioning concerns the shape of requests/responses exposed to clients (JSON structure, field names, endpoint paths), while the underlying data model (database schema, internal domain objects) can evolve independently as long as a translation/mapping layer (like DTOs) adapts between the internal model and each exposed API version's contract -- letting you refactor internals freely without forcing a new API version for every internal change.

// Internal domain model can change freely
public class ProductEntity { public decimal Price { get; set; } public string Currency { get; set; } }

// v1 DTO stays stable regardless of internal changes
public class ProductV1Dto { public decimal Price { get; set; } }  // USD assumed

// v2 DTO exposes the new capability
public class ProductV2Dto { public decimal Amount { get; set; } public string Currency { get; set; } }