Why you should version your api endpoints

so when you're building out web applications in general there is a very specific problem related to deploying new versions of your code that you may run into and this isn't specific to nextjs or versel this is just in general a problem that you're going to run into when you're building out websites and how do you circumvent this problem all right so versell published this article back in I think June 21st about skew protection so what the heck is skew protection so in the first paragraph they kind of describe the problem right so basically from your client you start hitting your apis and you get 404 requests after deployment or you get a 500 error because the client doesn't know that the new server deployment changed a API let's draw some diagrams about this all right so like always let's start with the user okay now the user when they first load your application they're going to be hitting a CDN or some type of server I'll just say like this is your your this is your server and if it's an xjs application they're going to download a certain version of your codebase right with nextjs you have your front end your back end it's all coupled together it's deployed in one monolithic type of thing so Step One is download version one of UI again next J has to split up into routes so let's pretend that you have a route called like uh dashboard okay so the user goes to SL dashboard that's going to download a very specific version of your application the user is going to show that in the browser the browser is going to load that JavaScript so then at some point set two the user will make some type of request right I'll say post request to update Tod do item and that will probably return some data to the user so return request body this should make sense this is like how all web applications work you load the UI user clicks on a form it submits some data and then the API sends back some some data back now the specific issue related to skew what they're talking about here is related to deployments all let's just put a robot here and I'll call this your cic deployment process or your pipeline whatever you want to call it all right so now let's talk about the deployment side of things which really highlights this issue so a developer let's say they come along and they're like you know what I need to update this API and I need to make it instead taken one additional argument and this is their required argument the users have to send this over when they do that post request okay so they make that change they push it to the repo and that kicks off a cicd deployment process and then at some point that needs to deploy your changes so I'm going to go ahead and say like deploy changes and technically what happened here is the user changed the API but they didn't really version that change so technically behind the scenes you do have a V2 of API inpoint so again someone changes the API requires some data that gets deployed out now that's deployed to your server and every new user who were to happen to go to your application after that new deployment I'm going to go ahead and say fresh new users so it's kind of apparent what I'm talking about here a fresh new user is going to get the UI with the updated code that knows to send over that post request with the additional parameter that this developer just added but the skew issue is that any existing user who hasn't gone and like you know refreshed their page manually or closed out of their browser and reloaded it they still have the old code because because remember this stuff is just loaded in your browser in memory and potentially in your cache so they still get V1 of the UI which is still thinking that it's talking the V1 of the API but unfortunately there's actually now a V2 of the UI and API how do you fix this issue cuz now in this existing user who has no knowledge that there's a new version deployed when they make that post request the server is just going to give back 500 status codes right the stuff's just going to fail because the server is saying hey you know what you need to provide that additional parameter but this this user's browser doesn't have that code so a couple ways to fix this issue and and I would say that they're all pretty complicated is the first thing is when you deploy a new API change you could basically notify the user and I've seen this in a couple of applications where like when a new deployment happens maybe through a websocket event or some type of mechanism where they do a post request to an old version API you show a modal and you say there's a new version of the API deployed would you like to refresh and then they click the refresh button that forces the browser to refresh the page it downloads the new code and then they're on version two of the UI which knows how to talk to the V2 API that's one approach the other approach is your version your API so you might have seen this on the back end where you'll have like a/ API V1 and you'll have an API vv2 and an API V3 as you can tell this is very problematic because you have to basically keep versioning all your apis it's a lot of work um this is probably much more useful for public interfaces and apis that people are using you don't want to break anything or existing apis now a common convention like I just mentioned is don't introduce breaking changes understand that there is a divide between the UI and the front end and any changes to this API should never be breaking okay so in this example where we added a required property you probably shouldn't have code like that if you're making a change on an existing API that people are using instead of saying that you have to pass in a required field in your code you should probably have a path that defaults this required field to something so that old users who are making the request do not get 500 errors they just get the old type of functionality you can also keep track like when the person does a post request you can actually provide a version number or you can kind of inspect the payload to see what it kind of looks like so like for example you could have a header or you can have some additional metadata that says like um we'll just do like UI version one or something so basically you add something to the request so that the API knows how to look at the request and say oh well you know you're still using the old version of the UI so let's just go ahead and internally route you to the old version of the code so you don't get issues these are different solutions that you could do to kind of make this all resilient to breaking your users and it's very important to keep that in mind when you're ever changing API or backend code now what skew protection does at least the versel solution is they actually just keep an entire running deployment of your old version so instead of like having to version your API manually it seems like what they're doing is they will actually spin up a separate API and somehow I think it kind of does all this for you under the hood let me know if I'm wrong I didn't really read through this I'm kind of just giving you a generic like how I think they're doing it um it looks like they have a deployment ID okay so they're probably passing in the request some type of deployment ID which behind the scenes I'm guessing there is some type of router internally with the nextjs code that looks at the deployment ID and based on what it is it's going to go ahead and Route you to either uh deployment a or deployment B I'll just go ahead and put apiv1 and API but this is kind of the solution that you would have to manually do yourself um or if you just use ver sale they kind of take care of that for you honestly I probably should have read through this article before I made this video but it looks like they kind of have um immutable deployment so basically when you do a deployment and then you do a another one right after that somehow they have like infrastructure that's kind of just sitting there running and because they're using serverless I mean this is super easy to just run a serverless function with a particular deployment ID um so it's always going to run the correct code which is supposed to work with your front end now remember there's a third aspect to all this there's a database and although versel says they provide skew protection although you can add mechanisms to prevent this issue from happening for users you still have a database and if you were to make breaking changes to that database it doesn't matter if you're on API V1 or V2 again you're going to have the same issue where the moment you run a migration script and you remove a column that V1 used to know about well then you've already kind of broken V1 right so you have to keep all this stuff in mind when you're deploying new versions of your code because there's so many different places where stuff has to be in sync and if that ever gets out of sync you're just going to get random errors in a bad user experience right you're going to get bugs uh crashing so the reason this is actually beneficial that versel kind of takes care of this for you is because otherwise if you don't have like a deployment mechanism to handle this issue what you end up doing is you have a bunch of copied and pasted code in your code base so that you can handle the various code paths that a user might be on and then you have to come back and remember to delete those old code paths and I do think this is still an issue with server actions cuz remember if you're using like a deployment to a VM you're just replacing the existing API in nextjs right so like in nextjs you'll have like server action V1 okay and then later you come along you say you know what I need to deploy a new version which is going to have your UI V2 your server actions V2 your API V2 and if you're deploying on a VM all you're doing is you're basically just deleting that and deploying a new version right so now all your users who are on the old version instantly they're going to get tons of Errors okay so I don't think even using server actions is going to help mitigate this issue you have to think of good solutions to combat this right that's all I wanted to share with you today I thought this was a really good topic to talk about hopefully you guys learned Wonder new things by watching this video if you did give me a thumbs up uh like always I have a Discord Channel you guys are welcome to join if you want to find a place to hang out and talk to other developers and ask questions other than that have a good day and happy coding

Channel: Web Dev Cody

Views: 12,331

Keywords: web development, programming, coding, code, learn to code, tutorial, software engineering

Id: ySo4-G6Ycfw

Length: 9min 55sec (595 seconds)

Published: Fri Dec 08 2023