BEYOND Status Codes! Better REST HTTP API Error Responses

when creating a restful hp api status codes can be a good way to indicate to the client if a request was successful or not but if there was a problem how do you tell the client specifically what was wrong well here's the most common thing that i usually see here are two made up request responses that i've made but these are based on real hp apis that i've consumed recently so this one is we've got back a 400 bad request if we look at the headers we've returned an application json and in the body we can see that we have a property called message which contains a human readable message of what went wrong that some product was not uh was already available for sale and then we have documentation which is a link to probably some docs that you're not likely going to read all right so the second example is a little bit different in i've also seen this where we have the status code as a 200 okay and but in the actual body we have a success property which is defined as false so we're not really using the status code in any meaningful way here just clearly returning 200 okay so we have to use this to determine whether our request was successful and this error object actually is useful because we have code which probably relates to some documentation that we can use at development time to figure out okay if it's this particular error code it means this exactly and we can build our ui or however we're consuming that appropriately then we have the type which is probably something very similar which is a key something again machine readable that we can use at design time and then info is just kind of that actual error message that's a human readable message that we may use and show the user or whatever the case may be so what do these two error responses have in common well they're errors but beyond that nothing they have nothing in common wouldn't it be awesome if there were a standard way to define errors from your hp api well the good news is there is and it's called problem details hey everybody it's derek martin from codopinion.com if you're new to my channel i post videos on software architecture and design so if you're into those topics make sure to subscribe problem details which is rfc 7807 aims to set out exactly solving that problem which is that status codes alone don't provide enough information to the client about what the issue is so most of times obviously when we're consuming apis we're doing it from a separate application from a separate service and we want more information just besides human readable text about what the actual problem is and that's what problem details set to kind of define a standard on a way to do that so i have a separate api that i've created that implements problem details and we're looking at pretty much the exact same type of error that i was showing earlier so i have a 400 bad requests but i have additional properties now that are really useful from consuming from an api so the first thing that's probably the most useful in my opinion is the type so the type is supposed to be a uri or a relative path to where you're making this request to that should be something stable the point of this is to provide similar to where i have that documentation uh uri it's supposed to be the same type of thing but it's something stable that you can use like an error code or like some type of error key something that's not going to be changing that's going to represent okay if i see this example.com problem slash already available that's going to stay the way it is that means something specific that i can then in my client show an appropriate error message or have some type of compensating action but that's a that defines specifically what the error is to our consuming api client so the second thing is the title and this is just human readable text about what the title of the error is nothing too special here maybe you want to show this to your actual end user the end client and i have a status code which represents the exact same status code that is coming back from our response detail same thing more of a description could be a longer thing again human readable so the instance property is a uri that's supposed to represent the actual specific occurrence of the actual problem and then lastly here i have the trace id which is a good example because this actually isn't part of the standard but it's called an extension you can basically add any additional properties or objects a part of your response for additional information so there's this kind of a set of these type title status detail instance which are a part of the standard but you can feel free to add additional properties as you see fit so the reason why extensions are pretty important in my opinion because if you're leveraging the type as a machine readable uri and you're using that as a key to identify specific problems or errors you then know when you're developing um looking at the responses if you see that particular type that represents certain error you know that at that point oh maybe there's these additional properties based on the documentation i read these additional properties should exist as extensions a part of my problem details response so if you're using asp.net core you can already do this today on the base controller there is a problem which you can then pass all the optional parameters like the detail the instance the status code the type and the type and what i'm doing here is that proves this point is that i have two different situations where i'm going to be returning a 400 because two different types of problems if this is in my warehouse code demo app here that i've been using in most my videos and if a product you're trying to set up a product that you can it's for sale now but if it's already for sale then we're turning the problem saying the product is already available for sale and that has a particular type that we've defined but if the product's unavailable and we're going to market uh being available for sale now to our customers but we don't actually have any quantity on hand well that's a separate problem so we're returning that specific type so if i look back to postman here here was the first one where the products was already available for sale and then now we can see our separate response here if the quantity is on hand we don't have any it's a different type of error but the schema is the same is the key part and if i look at the headers of this response we can see here that the content type that was returned is application slash problem plus json so if you're thinking yourself well that's really gross because i don't have any of that logic within a controller then you're probably going to want to use something like a middleware which i've been using this one for forever now and this is by christian hilang and if i said his name correctly and this is how you configure it's basically in your startup you're basically mapping exceptions to how you want to handle that and translate that into a problem details so you have that option as well so problem details doesn't solve every problem and the biggest issue i've had with it is when you have multiple problems that you want to define in the response the only way that i can find around this really is to define a specific type that your clients looking for that it knows that then at that point there's an extension that's probably an array of what the problem details actually are so if you're writing hp apis please take a look at problem details and consider implementing it people like myself that consume hp apis will thank you that we can finally stop writing custom one-off error handling code for every hp api we consume if you found this video helpful please give it a thumbs up if you have any thoughts or questions make sure to leave a comment and again please subscribe for more videos on software architecture and design thanks you

Channel: CodeOpinion

Views: 16,215

Keywords: http api errors, software architecture, software design, cqrs, event sourcing, design patterns, software architect, programming, .net, .net core, asp.net, asp.net core, microservices, service bus, rest, restful api, http bad request, http 400, restful, rest api, http api, http errors, restful errors, restful error, problemdetails, problem details, rfc7807, rfc 7807, problem details 7807, rest errors, rest 400, Rest bad request

Id: MfTLob6teJE

Length: 7min 52sec (472 seconds)

Published: Wed Apr 28 2021