Versioning requests

Evolution of API is a natural aspect, and is more desirable than a complete rewrite of your API. However, when it comes to pushing these changes to production you may encounter interoperability issues with legacy clients. One key factor when thinking about and designing the changes of your interface, is not to put the whole environment in a lock-down state until all legacy clients are updated.

One solution to this problem is the introduction of versioning to your DTOs. Consider the following request DTO:

// Version 0
public class Hello
{
  public string Name { get; set; }
}

After some time, you realize that it would be better to split the name into forename and surname, so you adapt the Hello class as:

// Version 1
public class Hello
{
  public string Forename { get; set; }
  public string Surname { get; set; }
}

If you try to call your operation with an instance of Hello from version 0, the call will result in a broken result (Forename and Surname get initialized with null...