How to structure asp.net api versioning and how to handle database migrations
Since I'm about to start an absolutely massive project, I want to get some final advice before I start planning out the structure of my backend and database
So I had 2 main questions (along with some smaller ones), how do I structure api versioning properly, should I use folders in the same project? Do I use multiple solutions in the same project with some shared logic in another solution? When I upgrade my api to v2, do I need to copy over every single endpoint from v1 or is there a more efficient way to do it without re writing potentially hundreds of endpoints for each version?
And more importantly, no matter how much database planning I do now, my schema will inevitably change to some degree, so I was wondering how I would handle this database migration with all my previous versions? For example if I'm on api V10 and make a scheme change, do I really need to go back to V1-9 (or whatever version is not yet deprecated) and change every database request related to my change? And how will I apply those changes to all databases that are present (my approach will create mulitple database with the same scheme but for different contexts)
For context: im using ASP.NET with the controller pattern as well as EF Core for the database, if any additional information is required feel free to request it
Thanks in advance
15 Replies
This sounds like a lot of planning for potential variants of complexity which might not even happen.
When it comes to API versioning, I wouldn't necessary plan ahead about whether you have to copy and forth endpoints - I think it's a case by case basis, usually you'd have a good reason to step up a version, right? I think you ideally also only start introducing additional projects once you actually need them, just to keep it simple. Nothing to be gained from optimization for complexity later on down the road if it blocks you from releasing a v1 in the first place
When it comes to database migrations, ideally you'll make the migrations downwards compatible
Or, you could at some point also introduce a "v2" table which essentially copies over data and can evolve on its own from that point onwards, if you code is capable of dealing with that
If you're really serious about the foreseen versioning complexity, I'd highly advise investing in a good bit of observability so you actually have a good idea of who interacts with which version on which frequency
And you'll likely have a pattern in place to inform clients about deprecations so you can chip away on making old versions obsolete
Supporting multiple versions is usually just something that is done for compatibility reasons, but you'll want to get rid of them as soon as possible to avoid combinatorial explosion on your business logic, having to support multiple variants
Could you explain the part with observability? I don't quite understand what that means :thinker:
Also yes, from what I'd say at the moment all database migrations are backwards compatible because it's likely I will only really add things and not remove old fields or smth
So basically the idea is that you have some kind of monitoring up to be able to record requests to your endpoints, so you always have a concrete number of who called vXX of your API
Also yes I'm aware that I'm probably worrying about things that can be solved at a time when it needs solving (because honestly if these cases apply my project likely succeeded and I will have the resources to let others do this) but I'd just like to have the peace of mind knowing that if shit were to hit the fan I would know how to somewhat stitch together a solution
Because if you are looking into deprecating versions, you want to back it up with numbers
Ah, so you mean like basic logging / analytics and all that stuff?
Yep, exactly.
For API versioning there are a few good resources out there
Nick has a video on it as well
Nick Chapsas
YouTube
Implementing Modern API Versioning in .NET
Join the NDC Conferences Giveaway: https://mailchi.mp/nickchapsas/ndc
Check out my courses: https://dometrain.com
Become a Patreon and get source code access: https://www.patreon.com/nickchapsas
Hello everybody I'm Nick and in this video I will show you how you can implement modern API versioning in .NET using the latest tooling available. In ...
Is there a recommended way to structure versioning?
I heard some people just create folders like V1, v2 while others create multiple solutions for each version and then they have a "shared" logic collection
I'll check it out in a bit, thanks
Gotta hit the bed, but I can give you some more info tomorrow 😄
Bet
Thanks a lot btw :SCballin:
Okay, so when it comes to versioning, I usually structure my solutions in a vertical slice manner, so I tend to either
a) If I want to migrate one endpoint, place it in the same controller / minimal API group
or
b) If I want to migrate an entire set, I'll usually just place the file alongside
So you're doing: MessageController.cs, MessageControllerV2.cs or?
And what about changing DTOs
Yeah
Well with dtos, I kind of prefer to use new ones so they can evolve independently
But once again, by-case basis I think
Potentially your versioning is not due to changes in the types
Hm
My versioning will mostly be due to completely different JSON structure in requests and responses that would break V1
If I just want to add new things I can do it in V1