I have been asked to get involved with a Team that is currently having delivery issues for various reasons. During my review I came across an acceptance criteria on a user story;

If you call v1 of the API with Field1 it should fail with a validation message

Field1 does not currently exist in v1 of the API, it is being added to V2.

When I questioned the AC, I ended up with the following explanation;

Due to constraints, we have decided to reuse the schema models for v1 in v2 and add the new properties to these existing models. We will also be adding validation to ensure that you cannot send these properties in the existing (Production) v1.

My initial conversations around this suggested this was due to time constraints, it further turns out that this might have been a discussed and agreed position amongst the Team.

When I explained what I felt were some fundamental concerns with this, those concerns were acknowledged and I was told "we did want to do it that way".

Further conversations have now produced a number of documents;

  1. A document that highlights valid approaches to versioning (I briefly read this) and agree with the points
  2. An analysis document that ultimately ended up guiding the Team to think that reusing and extending models in multiple versions of an API is very far from being a good thing to do.

When I explained how I felt that would affect the schema, I was told this was hand-cranked (which I guess is a valid thing to do, not that I would do that).

A further challenge I put forward was the cumulative effort of adding a new property and then adding validation to ensure it could not be used in an API version is was not designed for. Add up the unit tests, system testing and integration testing of all of these negative conditions for schema properties that should not even exist.

Anyway, this all came to a head today with a meeting in which I presented my initial thoughts, told the engineers it was a bad idea any day of the week and that the effort to do this in a better approach would come in less than the effort to add all the validation to an API that needs to support distinct versions with a shared model.

A brief summary of what I proposed;

Independently versioned controllers/model and whatever changes were then needed to persist both the V1 and V2 models to the repo.

We did agree that the repo needed to have all the new properties of the v2 schema so we have to uplift that regardless and because there were no breaking changes, it would support both v1 and v2 without any issues.

The outcome of this was a position of defending their design decisions, claiming the proposed way would add too much complexity and the integration into the repo would not support differing versions of the data without many, additional changes (using base classes and interfaces as parameters into the repo was apparently a no-go). The existing design also supposedly provided a pattern for future changes because they did abstract the validation away from the model itself, so a precedent was set that this was a good thing and "worked"

I briefly discussed this with a few peers who all agreed with the overall opinion that this is not a particularly great idea. I bounced the ideas of my overall technical lead who ultimately has the final say on this as far as I am aware, he also agrees.

Although I have not yet seen this document that ultimately ended up being used to make this decision, I am keen to understand if there were viable reasons for doing so. I have been given a certain amount of authority and can likely get a change forced upon them. On the flip side, I am also in a position to get agreement to grant the engineers time to implement things more pragmatically if the net result is a better product that will fit better with continual change, and patterns to help that happen.

The engineers claim to want to be able to write solid code, but then why would this be seen as anything but a bad idea.

Generally curious as to whether my take on this is wrong, I am always open to learning.

I would add that there are no breaking changes in this revision, but does not mean they won't be made in the future.

  • After reading this a few times (please add a TLDR version) it seems to be a trade-off between reusing models which causes work on v1 endpoints, or creating new models which causes work on various other places such as validations. Correct?
    – Rik D
    Jan 24 at 23:30
  • not 100% clear on why you think its bad? are they deploying v1 with v2 model classes using a schema check to make sure only a subset of fields is used?
    – Ewan
    Jan 25 at 11:39
  • 60% of this question seems to be only distracting noise on the back-and-forth discussion with the team. I am sure if you can manage it to strip these parts out of the text and focus on the core, this question will get a lot more readers, more answers and less close votes.
    – Doc Brown
    Jan 25 at 20:20

1 Answer 1


Reading between the lines of your question it looks to me like you are implementing multiple versions of an api in a single application?

I think this is the root cause of your issue. Instead (assuming these are web apis) I would leave API v1 unchanged and deploy a v2 with the altered code base to different machines.

If you work this way they you can expand the same models and controllers as required without having to duplicate and support versioned classes, as the deployment itself is versioned

If you want to fiddle with version 1 then branch from the point where the code was v1 and make a v1.1 branch

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.