Intercept ANY Minimal API Response in ASP NET Core

if we're building ASP onore minimal apis what's the way that we can intercept every single response that we're sending back to the caller hi my name is Nick centino and I'm a principal software engineering manager at Microsoft in this video we're going to look at a mechanism that we can leverage in our asp.net cor apps that allows us to intercept the responses we're about to send manipulate them in whatever way we'd like and then continue to send that on to the caller now if you're thinking middleware might be the thing to solve this you're potentially right but we have another tool that we can leverage and we're going to look at that in this video a quick reminder that if you like this kind of content subscribe to the channel and check out that pin comment for my courses on dome train with that said let's jump over to visual studio and see how this works in one of my previous videos which I will link above so you can go check that out if you haven't already we were looking at being able to handle specifically error messages to be able to get those responses back to the user in a way that was formatted more uniformly and that way if we had common exception types we could have a consistent way that that went back over the API but if I scroll down and we start looking through this what we started to see is that when we throw exceptions like this we have error handling middleware using this error Handler here on line 18 and that would allow us to package up our response inside of an API response record so if I scroll down a little bit more here you'll see that I was creating these API response records yes if you're looking at this and you're wondering what it's doing this is something where the one of n get package would be great because we don't have discriminated unions in C but the way that the Json gets written out based on my settings right now if you populate one of these and not the other you'll only see one or the other on the response but my goal was that we had a common response type that we could send back in that video though we only looked at doing it for error messages so again if I scroll back up to this error middleware not super important to go through the details but it was always returning an API response and that meant errors were consistent what happens on the happy path because that's the error path right if we scroll back up here if you look at this part so line 34 through 38 if you consider that I might have multiple end points and I want to always package them up you can think about putting it in like an envelope right so anyone calling your API regardless of the route is always going to have a consistent envelope that your data is inside of maybe you want to put a version on that for me I wanted something like a success flag just to easily check things and that way if success is true you know that you can go look at the data or the payload and if success is false you should be specifically looking for an error again you might have different needs I'm not telling you it's right or wrong this is just a mechanism that we can look at to start putting an envelope around our responses in this case this part here is not going into the envelope and in fact if I wanted to do that without using anything fancy I would have to go make a new API response here and the way that I have this set up looks pretty nasty but everyone would have to do something like this right and you could go build like I said use the one of nougat package or build an API to go construct this that only takes one or the other could totally do that but the problem or one of the challenges with doing this is that anytime you go make an end point you need to remember that anything you're returning you need to go bundle up this way the way that we worked around that for the errors was with middleware we said hey look someone threw an exception we're going to bundle this all up in our little envelope and send it across in the happy path which is here how do we make sure that happens in order to demonstrate this I'm going to first run this example we're going to make sure that the validation fails and I will show you the error case just so that you have a a starting point I'm going to go run this and we should see some Jon come back that represents that envelope structure of the API response record before we continue on this is just a quick reminder that I do have courses available on D train if you're just getting started in your programming journey and you want to learn C you can head over to D train I have a getting started in C course it's approximately 5 hours of content taking you from absolutely no experience to being able to program in C and after that I have my deep dive course which will take you to the next level with another 6 hours of content so that you can start building basic applications head over to D pran and check it out let's head back to the video by pull this up on the screen here you can see that the pattern that we have is that we have an error property at the top and a success property at the top right success is false we don't see any other top level property that's because my Json settings for nulls are not being written out so it's something you can customize and then inside here when I have a particular error type this is for validation specifically I set this up we can go have a message an exception type and stack Trace where two things in particular that I wrote in like an if for debugging again you can do whatever you want here that's the previous video but I wanted to show you this is what the envelope looks like when we're dealing with error cases how does this look when we want it to be the happy path so the challenge here is that middleware is something that could work but I think there's a better fit for that and I'm going to show you this endpoint filter so you'll notice I've gone ahead and I've added on endpoint filter here and if I go and change this to true I want to show you the output of this and then we'll walk walk through what this endpoint filter does because it's very simple so if I go run this you'll see this is really basic stuff right so let me pull this up on the screen beside what we got going on oh and it's not fair I cheated a little bit right you're seeing some duplicated stuff because we don't have to go wrap this anymore so let me go show you this without cheating you don't need to put the API response in fact I could check to make sure if anyone already put this in an envelope don't do it maybe that's a little optimization we could make but if if I run this once more we should see that we don't have a double envelope so we get the data which is value 1 2 3 and you can see something else being set to null here that's why we don't see that property in the Json before or after value it's because it's null the Json settings will not write that out but this is put inside of a little envelope how did we make sure that we could have this happen on this route automatically for us that is the response filter that I have here so this endpoint filter this is the interface you need to implement and if you noticed if I scroll back up very quickly I had to add that on to the minimal API route that we're accessing I'll go back down and we can look at the definition of it truly this is how simple it is right you have the method that you need to implement for the interface and then we're going to be able to get the result and then from there we just wrap it in the envelope there's literally nothing more in this particular case and what I could have done like I said is we could do something like if result like we could add this as a little optimization so that we don't risk like double envelopes we could do something like that you could even write it such that maybe in debug mode if someone's wrapping this in an API response already maybe you want to enforce they don't you could throw exceptions and say hey like you know almost have a contract for your code and that way anyone developing inside of your application if they're not supposed to be wrapping it in an API response themselves you could catch them and tell them hey don't do that or you could just allow them to go pass it through and you don't have to do the work here you have options I'm not saying what's right or wrong but but this is how this I endpoint Filter Works and that way when the uh the sort of return value of your method call or your route call is bubbled up we are going to put it inside of this envelope here that's how this works and this works very well on our single route that we have there is a bit of a trick and one of the challenges here is that it's not yet Universal or Global for our application so if I go do this and I add another endpoint right what I would like to have happen I going to call it weather forecast 2 I want to make sure that any route I add is going to pick up this functionality I want everything to wrap responses in an envelope you may not want that for your application that's totally cool I'm just saying for what I'm developing that's what I would like to have and you'll notice that whether forecast works as expected because that's the first one we looked at but if I put a two here notice that this one is not wrapped inside of the envelope and it's because if I go back to the code I need to add this endpoint filter onto every single route that may be cool for you because you want to have full control over every route but for me how do I make sure that I can have every route automatically get this and there's a little trick that we can use I'm going to scroll back up here and uncomment this code that I had hiding in plain sight but we have a way to do a uh group that is empty and this means that once we have this empty group I'm calling it Global because it's sort of like this root you could call it maybe root as well it's root grouping because it's empty there's nothing in the URL path that you have to go add so this will just work and that means I can take off this and I don't have it on the other one right so both of these routes do not have an endpoint filter explicitly defined we just have it on this root group and let me go make sure that I change this one because I would have forgot to do that but now we have I'm just collapsing them so you can see two get methods that we can go Implement and call here and neither of them have an endpoint filter but if we go run this we can see that weather forecast was the first one we looked at again this is off of now the root grouping it does not have the endpoint filter on the specific route if I put a two here we get the same thing so now both of these because they're off of this group do in fact get that response filter or my standard response filter that I built perhaps you have different parts of your application that have different groupings and you only want the endpoint filter on those maybe not globally again this will clearly work if you don't want to do it at the global level you could do something like weather here and then instead we have something like this you could have that and we could have a a weather group and that way maybe you have like a different route that says hello and you don't want this kind of envelope on the response you're able to customize this as you'd like but I wanted to show you that little cheat code where you have an empty group name and that way you can apply things onto that and sort of have this endpoint filter applied globally so at this point we've now seen how we can handle errors and make sure that those are wrapped inside of an envelope and on the happy path especially if we want global or specific routes to have an envelope around the responses we can use an i endpoint filter to go hook that up if you thought this was interesting and you want to see more about building modular asp.net core applications you can go ahead and check out this video next thanks and I'll see you next time