We Keep Coding

API Versioning - What do I do if model changes

I'm fairly new with APIs and versioning but from what I understand, the developer (which is me) should retain the code if there will be a contract breaking change for the API. Correct me if I'm wrong but I consider Model changes as contract breaking change.
So my question is - Do you make a new model (ex. ModelName.V2) just for the sake of versioning? Is there a better way to do this? This would mean even a slight change in property in my model would mean I would iterate it to another version.
p.s. let me know if I need to edit my question as I'm also fairly new in StackOverflow.
Sample
public class Product
{
public int ID {get;set;}
public string Name {get;set;}
}
and accompanying Controller
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
public class Products : Controller
{
Product[] prod = new Product[]{
new Product(){ID = 1, Name = "T-Shirt"},
new Product(){ID = 2, Name = "Jeans"}
};
[HttpGet]
[ActionName("gotcha")]
public IActionResult GetProduct()
{
return Ok(prod);
}
}
and for V2 Controller
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/[controller]/[action]")]
public class V2.Products : Controller
{
[HttpGet]
[ActionName("gotcha")]
public IActionResult GetProduct()
{
var trash = "Hello World!";
return OK(trash);
}
}
The above codes are what I understand as contract breaking and needed versioning and below is my problem with Model contract breakage:
public class Product
{
public int ID {get;set;}
public string Name {get;set;}
public decimal Price {get;set;}
}
So the sample above shows I added a new property. This I consider as contract breakage and do I iterate a new controller version and then retain the old Model as well? In the future this will be messy if I keep legacy versions.

First, you only need to reversion if there's a breaking change. Not everything is necessarily a breaking change, and typically adding a new property is not in fact a breaking change. Outdated clients should simply ignore it, and if not, that's more on the client than you, as they'd be doing something weird/wrong to cause anything to break that way. You need to be more concerned about changes or deletions, which from a client perspective are kind of the same thing; with a change, it's as if the old property was removed and new one was added. Even then, though, it only matters if the name or the type changes. Any under the hood processing doesn't matter, and technically, even if you change the property name, you can utilize something like the JsonProperty attribute to make the serialization return the old name, if you want.
Assuming you do have a breaking change, then yes, you should create a new version of your model class, and probably a new action/controller to go with it, both named with the new version number, i.e. Product2 and GetProduct2 and/or Product2Controller, etc. Yes, this can lead to code duplication, but there's two things you can do to minimize that:
Use inheritance if possible. For example, Product2 can inherit from Product and simply override whatever property needs to change. If you just add a new GetProduct2 action, you can factor out the original code for GetProduct into a private generic method GetProduct2<TProduct>, and then reimplement the original (and new) method to simply return that, i.e. return GetProduct<Product>(); and returnGetProduct();`. These are just examples. There's many different ways to handle this, but the point is that it doesn't necessarily require major code duplication to do versioning.
If you notice your codebase is starting to feel cluttered, you can begin deprecating API versions. Issue a notice to your clients that one or more of your oldest versions are now deprecated. Then, after a reasonable amount of time (depending on the complexity of the changes required to get up to date), remove that old code in a new release. This will of course break any outdated clients, but they were forewarned and given time to change, so if they don't that's on them. You'll notice all the big boys do this from time to time. I know I've been receiving a ton of emails from Facebook warning of pending API version removals. That's essentially what they're doing behind the scenes: cleaning their codebase.

When I do a API versioning. I add a new model with the Version number just to be able to track down the changes in data data structure, example:
public class ProductV2
{
//New attributes
}
I would just inherit attributes from the previous version, if the new model is similar to the old one plus new attributes:
public class ProductV2 : Product
{
//New attributes
}
Hopefully I understood your question this time.

How to move/copy all the objects from one IList to other

I am working on ASP.NET MVC 4 project. I have ViewModel which is :
public class SectionModel
{
public Menu Menu { get; set; }
public IList<Document> Documents { get; set;}
}
then in my action I have :
Menu menu = unitOfWork.MenuRepository.GetById(Id);
IList<Document> docs = unitOfWork.DocumentRepository.GetBy(x => x.MenuID == menu.MenuID).ToList();
SectionModel model = new SectionModel();
model.Menu = menu;//???
model.Documents = docs;//???
So menu and docs are fetched from the database. The when I create new instance of SectionModel I want to pass the values but I'm not sure what's the proper way. In fact what is the way to assign the single object menu and the IList<Document> docs?
I was thinking of model.Menu.Add(menu) and then some foreach like:
foreach (var doc in docs)
{
model.Documents.Add(doc);
}
but I'm not sure that's the proper way to do this.

There's a common thread of thought I see all the time, about using interfaces to declare lists (or some other collection type) when declaring properties. I understand the motivation to do this, should you ever decide to throw the standard .NET List<> class in favour of your home-grown.
I've yet to see a decent reason for this. You're falling foul of the "let's abstract everything away in all circumstances, even if they are not particularly relevant" idiom. (And let us not forget that interfaces on POCOs are not particularly ORM-friendly.)
If I were designing an API, I might use IList, even if everything worked with a List internally. Truth is, it's a bit of a misnomer. I've never had cause to use an IList<> because that's all it is... a programmatic misnomer.
As Julie says, swap out that interface and put a decent class in there (List<>, for example).. not only is it concrete, but you can then use it as it should be used. People love to band about the terms of interfaces always in case I change my mind but that just stinks of bad design.
Don't be afraid to use a real, concrete class.

I recommend interfaces if your code should inter-operate with others projects but underneath you are using always List<T>
you have to change this
public class SectionModel
{
public Menu Menu { get; set; }
public List<Document> Documents { get; set;}
}
and use
model.Documents.AddRange(docs);

If you consider to use AutoMapper, here's the code:
First, make sure you have AutoMapper installed. Use package-manager and type command package-install AutoMapper.
var anonymous = new {
Menu = unitOfWork.MenuRepository.GetById(Id);,
Documents = unitOfWork.DocumentRepository.GetBy(x => x.MenuID == menu.MenuID).ToList();
};
var sectionModel = AutoMapper.Mapper.DynamicMap<SectionModel>(anonymous);
Any why I suggest to use this ?
Point 1: IList is fine here. Somebody (or you) had put there during design and it's just fine. According to me, changing to List is unnecessary. Your model object is just there to put the information and IList is fine because your sectionmodel class is not going to change or delete any entry from it. Since its just there for enumeration its fine.
Point 2: You can do the manual mapping. But, AutoMapper just maintains code readable.

Building Generic Apps - Allowing Customer-specific Options

I've built an open source application, and I'd be curious to know how others are handling customer-specific requests. It's important to me to keep the app simple; I'm not trying to make it all things for all people. Apps can get bloated, complex, and just about unusable that way. However, there are some customer-specific options that would be nice (it just wouldn't apply to all customers). For example...
Say we have a domain entity called Server. In the UI, we let a customer pick from a list of servers. For one company, it's helpful to filter the servers by location (US, Germany, France, etc...). It would be easy enough to add a server property like this:
public class Server
{
public Location Location { get; set; }
// other properties here
}
My concern is that Server could become bloated with properties over time. And even if I only add location, not all customers would care about that property.
One option is to allow for user-defined fields:
public class Server
{
public string UserField1 { get; set; }
public string UserField2 { get; set; }
public string UserField3 { get; set; }
// etc...
// other properties here
}
Is that the best way to handle this? I don't like the fact that type safety is gone by making everything a string. Are there other/better ways that people are handling issues like this? Is there even a design pattern for something like this?

In my opinion, a good design pattern for something like this is to use schemas at the database level and then basic inheritance at the class level.
CREATE TABLE dbo.A (
ColumnA INT NOT NULL PRIMARY KEY AUTO_INCREMENT,
ColumnB VARCHAR(50),
ColumnC INT,
etc.
)
And now we have a client who needs some specific functionality, so let's create an extension to this table in a different schema:
CREATE TABLE CustomerA.A (
ColumnA INT NOT NULL PRIMARY KEY,
Location VARCHAR(50)
)
But now we have another client who needs to extend it differently:
CREATE TABLE CustomerB.B (
ColumnA INT NOT NULL PRIMARY KEY,
DataCenterID INT
)
Though the fields may not be relevant, you get the idea, and so now we need to build the customer specific domain models here:
public abstract class A
{
public int ColumnA { get; set; }
public string ColumnB { get; set; }
public int ColumnC { get; set; }
}
public class CustomerA_A : A
{
public string Location { get; set; }
}
public class CustomerB_A : A
{
public int DataCenterID { get; set; }
}
And so now when we need to build something for Customer A, we'll build their subclass, and for Customer B theirs, and so on.
Now, FYI, this is the beginnings of a very dynamic system. I say that because the piece that's missing, that's not yet dynamic, is the user-interface. There is a significant number of ways that can be accomplished, but way outside the scope of this question. That is something you'll have to consider. I say that because the way you manage the interface will determine how you even know to build which subclass.
I hope this has helped.

The usual approach early on is to use the config XML files for this sort of thing. But programming for client-specific needs requires a whole mindset around how you program. Refer to this answer to a similar question.

Of course it always depends on how much customization you want to allow. In our product we went as far as enabling users to completely defined their own entities with properties and relations among them. Basically, every EntityObject, as we call our entities, in the end consists of a value collection and a reference to a meta-model describing the values within them. We designed our own query language that allows us to query the database and use expressions that are translate-able to any target language (although we currently only do SQL and .net).
The game does not end there and you quickly find that things like validation rules, permissions, default values and so on become a must have. Of course all of this then requires UI support, at least for the execution of the meta-model.
So it really depends on the amount of adjustment a end-user should be able to perform. I'd guess that in most cases simple user fields, as you described, will be sufficient. In that case I would provide a single field and store JSON text within that. In the UI you can then provide at least a semi-decent UI allowing structure and extensibility.

Option 1: Say "no". :-)
And while I say that (half) jokingly, there is some truth to it. Too often, developers open themselves up to endless customization by allowing one or two custom features, setting the snowball in motion.
Of course, this has to be balanced, and it sounds like you may be doing this to an extent. But if you truly want to keep your app simple, then keep it simple and avoid adding customizations like this.
Option 2: Inheritance.
If you really need to add the customization, I would lean the way of building a base class with all "standard" options, and then building customer-specific classes containing customer-specific optimizations.
For example:
public class Server
{
// all standard properties here
}
Then for Joe's Pizza, you can have:
public class JoesPizzaServer : Server
{
public Location Location { get; set; }
}
The side-benefit to this is that it will allow you to base your presentation views off of the client-specific (or base) models.
For example, in MVC you could set up your view models like this, and then you could have specific views for each customer.
For example, Bob's Burgers would have its own view on the base model:
#model MyApp.Server
#* implement the base form *#
And Joe's Pizza's view would use the custom model:
#model MyApp.JoesPizza
#* implement the base form -- a partial view -- with addtional custom fields
MVC does a really good job of supporting this type of pattern. If you're not using MVC (maybe WPF or Web Forms), there are still ways to leverage partial "view" files for accomplishing something similar.
Of course, your database can (and probably should) support a similar inheritance model. Entity Framework even supports various inheritance models like this.

I may be wrong here, but it looks like you want to handle different versions of your software with the same code base. I can think of two approaches for this:
Actually define different versions for it and handle changes for each client. This won't give you problems from the domain-modeling point of view, but will require a supporting infrastructure, which will have to scale according to your client requirements. There are some related questions out there (e.g. this, this and this).
Handle this at the domain-model level, as a user-defined configuration. The advantage of this approach is that you don't have to incorporate multiple versions of your software, but this comes at the expense of making your model more generic and potentially more complex. Also your tests will surely have to be adapted to handle different scenarios. If you are going in that direction I would model an object representing the attribute (with a name and a value) and consider the Server class as having a collection of attributes. In that way your model still captures your requirements in an OO style.
HTH

I approach from Python that I think would work rather well hear is a dictionary. The key is your field name, the value is the, errrrr... value ;)
It'd be simple enough to represent in a database too.

capture changes to properties of an object

I have multiple business objects in my application (C#, Winforms, WinXP). When the user executes some action on the UI, each of these objects are modified and updated by different parts of the application. After each modification, I need to first check what has changed and then log these changes made to the object. The purpose of logging this is to create a comprehensive tracking of activity going on in the application.
Many among these objects contain contain lists of other objects and this nesting can be several levels deep. The 2 main requirements for any solution would be
capture changes as accurately as possible
keep performance cost to minimum.
eg of a business object:
public class MainClass1
{
public MainClass1()
{
detailCollection1 = new ClassDetailCollection1();
detailCollection2 = new ClassDetailCollection2();
}
private Int64 id;
public Int64 ID
{
get { return id; }
set { id = value; }
}
private DateTime timeStamp;
public DateTime TimeStamp
{
get { return timeStamp; }
set { timeStamp = value; }
}
private string category = string.Empty;
public string Category
{
get { return category; }
set { category = value; }
}
private string action = string.Empty;
public string Action
{
get { return action; }
set { action = value; }
}
private ClassDetailCollection1 detailCollection1;
public ClassDetailCollection1 DetailCollection1
{
get { return detailCollection1; }
}
private ClassDetailCollection2 detailCollection2;
public ClassDetailCollection2 DetailCollection2
{
get { return detailCollection2; }
}
//more collections here
}
public class ClassDetailCollection1
{
private List<DetailType1> detailType1Collection;
public List<DetailType1> DetailType1Collection
{
get { return detailType1Collection; }
}
private List<DetailType2> detailType2Collection;
public List<DetailType2> DetailType2Collection
{
get { return detailType2Collection; }
}
}
public class ClassDetailCollection2
{
private List<DetailType3> detailType3Collection;
public List<DetailType3> DetailType3Collection
{
get { return detailType3Collection; }
}
private List<DetailType4> detailType4Collection;
public List<DetailType4> DetailType4Collection
{
get { return detailType4Collection; }
}
}
//more other Types like MainClass1 above...
I can assume that I will have access to the old values and new values of the object.
In that case I can think of 2 ways to try to do this without being told what has explicitly changed.
use reflection and iterate thru all properties of the object and compare
those with the corresponding
properties of the older object. Log
any properties that have changed. This
approach seems to be more flexible, in
that I would not have to worry if any
new properties are added to any of the
objects. But it also seems performance
heavy.
Log changes in the setter of all the properties for all the objects.
Other than the fact that this will
need me to change a lot of code, it
seems more brute force. This will be
maintenance heavy and inflexible if
some one updates any of the Object
Types. But this way it may also be
preformance light since I will not
need to check what changed and log
exactly what properties are changed.
Suggestions for any better approaches and/or improvements to above approaches are welcome

I developed a system like this a few years ago. The idea was to track changes to an object and store those changes in a database, like version control for objects.
The best approach is called Aspect-Oriented Programming, or AOP. You inject "advice" into the setters and getters (actually all method execution, getters and setters are just special methods) allowing you to "intercept" actions taken on the objects. Look into Spring.NET or PostSharp for .NET AOP solutions.

I may not be able to give you a good answer, but I will tell you that in the overwhelming majority of cases, option 1 is NOT a good answer. We're dealing with a very similar reflective "graph-walker" in our project; seemed like a good idea at the time, but it is a nightmare, for the following reasons:
You know the object changed, but without a high level of knowledge in the reflective "change handling" class about the workings of objects above it, you may not know why. If that information is important to you, you have to give it to the change handler, most l;ikely through a field or property on the domain object, requiring changes to your domain and imparting knowledge to the domain about the business logic.
Changes can affect multiple objects, but logs for changes at every level may not be desired; for instance, the client may not want to see a change to a Borrower's outstanding loan count in the log when a new Loan is approved, but they do want to see changes due to consolidations. Managing rules about logging in these cases requires change handling classes to know about more of the structure than just one object, which can very quickly make a change-handling object VERY big, and VERY brittle.
The requirements of your graph walker are probably more than you know; if your object graph includes backreferences or cross-references, the walker must know where it's been, and the simplest comprehensive way to do that is to keep a list of objects it's processed, and check the current object against those it's handled before processing it (making anti-backtracking an N^2 operation). It must also not consider changes to objects in the graph that will not be persisted when you persist the top level (references that are not "cascaded"). NHibernate gives you the ability to plug into its own graph-walker and abide by the cascade rukles in your mappings, which helps, but if you're using a roll-your-own DAL, or you DO want to log changes to objects that NHibernate won't cascade to, you're going to have to set this all up yourself.
A piece of logic in a handler may make a change that requires an update to a "parent" object (updating a calculated field, perhaps). Now, you have to go back and re-evaluate the changed object if the change is of interest to another piece of the change handling logic.
If you have logic that requires creation and persistence of a new object, you must do one of two things; attach the new object to the graph somewhere (where it may or may not be picked up by the walker), or persist the new object in its own transaction (if you're using an ORM, the object CANNOT reference an object from the other graph with a "cascade" setting that will cause it to be saved first).
Finally, being highly reflective in both walking the graph and finding the "handlers" for a particular object, passing a complex tree into such a framework is a guaranteed speed bump in your application.
I think you'll save yourself a lot of headaches if you skip the "change handler" reflective pattern, and include the creation of audit logs or any pre-persistence logic in the "unit of work" you're performing up at the business layer, through a set of "audit loggers". This allows the logic making the changes to employ an algorithm selection pattern such as Command or Strategy to tell your audit framework exactly what kind of change is happening, so it can pick the logger that will produce the required logging messages.

See here how adempiere did the changelog: http://wiki.adempiere.net/Change_Log

Validation Framework in .NET that can do edits between fields

From my experience many validation frameworks in .NET allow you to validate a single field at a time for doing things like ensuring a field is a postal code or email address for instance. I usually call these within-field edits.
In my project we often have to do between-field-edits though. For instance, if you have a class like this:
public class Range
{
public int Min { get; set; }
public int Max { get; set; }
}
you might want to ensure that Max is greater than Min. You might also want to do some validation against an external object. For instance given you have a class like this:
public class Person
{
public string PostalCode { get; set; }
}
and for whatever reason you want to ensure that Postal Code exists in a database or a file provided to you. I have more complex examples like where a user provides a data dictionary and you want to validate your object against that data dictionary.
My question is: can we use any of the existing validation frameworks (TNValidate, NHibernate Validator) for .NET or do we need to use a rules engine or what?? How do you people in the real world deal with this situation? :-)

There's only one validation framework that I know well and that is Enterprise Library Validation Application Block, or VAB for short. I will answer your questions from the context of the VAB.
First question: Can you do state (between-field) validation in VAB?
Yes you can. There are multiple ways to do this. You can choose for the self validation mechanism, as follows:
[HasSelfValidation]
public class Range
{
public int Min { get; set; }
public int Max { get; set; }
[SelfValidation]
public void ValidateRange(ValidationResults results)
{
if (this.Max < this.Min)
{
results.AddResult(
new ValidationResult("Max less than min", this, "", "", null));
}
}
}
I must say I personally don't like this type of validations, especially when validating my domain entities, because I like to keep my validations separate from the validation logic (and keep my domain logic free from references to any validation framework). However, they need considerably less code than the alternative, which is writing a custom validator class. Here's an example:
[ConfigurationElementType(typeof(CustomValidatorData))]
public sealed class RangeValidator : Validator
{
public RangeValidator(NameValueCollection attributes)
: base(string.Empty, string.Empty) { }
protected override string DefaultMessageTemplate
{
get { throw new NotImplementedException(); }
}
protected override void DoValidate(object objectToValidate,
object currentTarget, string key, ValidationResults results)
{
Range range = (Range)currentTarget;
if (range.Max < range.Min)
{
this.LogValidationResult(results,
"Max less than min", currentTarget, key);
}
}
}
After writing this class you can hook this class up in your validation configuration file like this:
<validation>
<type name="Range" defaultRuleset="Default" assemblyName="[Range Assembly]">
<ruleset name="Default">
<validator type="[Namespace].RangeValidator, [Validator Assembly]"
name="Range Validator" />
</ruleset>
</type>
</validation>
Second question: How to do complex validations with possible interaction a database (with VAB).
The examples I give for the first question are also usable for this. You can use the same techniques: self validation and custom validator. Your scenario where you want to check a value in a database is actually a simple one, because the validity of your object is not based on its context. You can simply check the state of the object against the database. It gets more complicated when the context in which an object lives gets important (but it is possible with VAB). Imagine for instance that you want to write a validation that ensures that every customer, at a given moment in time, has no more than two unshipped orders. This not only means that you have to check the database, but perhaps new orders that are added or orders are deleted within that same context. This problem is not VAB specific, you will have the same problems with every framework you choose. I've written an article that describes the complexities we're facing with in these situations (read and shiver).
Third question: How do you people in the real world deal with this situation?
I do these types of validation with the VAB in production code. It works great, but VAB is not very easy to learn. Still, I love what we can do with VAB, and it will only get better when v5.0 comes out. When you want to learn it, start with reading the ValidationHOL.pdf document that you can found in the Hands-On Labs download.
I hope this helps.

I build custom validation controls when I need anything that's not included out of the box. The nice thing here is that these custom validators are re-usable and they can act on multiple fields. Here's an example I posted to CodeProject of an AtLeastOneOf validator that lets you require that at least one field in a group has a value:
http://www.codeproject.com/KB/validation/AtLeastOneOfValidator.aspx
The code included in the download should work as an easy to follow sample of how you could go about it. The downside here is that Validation controls included with ASP.Net don't often work well with asp.net-ajax.