Web Services - Best Practices creating REST API's

foreign and welcome to another video today we're going to talk about the best practices when creating rest apis welfare apis can improve development and Integrations a lot and even if you have knowledge on this topic I would recommend you to save because you might learn something new I'll using.net for these examples produce should be able to use any of these recommendations on any language or technology let's get started okay let's start by defining the syntax or not the syntax day the structure of our endpoints normally I would recommend to add a version a even if you have an API that doesn't change a lot through time it's where to have a version when because you might need to do really critical or breaking changes in the future so having an opportunity is the best way even though using these recommendations this would be this should be really feature proof so let's but in any case add a version 2 to your apis then you have your entity endpoint which should be plural in this case it's users so a it should always be Pro because the that endpoint itself should always return a collection even though it can be a filtered collection it should always return a collection even if they if even if there's no items on it it should return an empty array there is always there always should be an okay result with an array on it empty or not empty like I have here here I'm sending an okay with a word statement how do you manage the filters the filter should be managed by query parameters the query parameters are the basic way to to search into a a collection in the of a rest API so here I have my collection my users and then by using the query parameter I filter if it's not available if no one provides me this parameter then I should return everything but if the parameter it's there and then I should use that parameter to search into the into the The Collection the way you want to search it depends on you and your business and your case or what you want to allow in your Integrations because for example in this case I'm using a contains but if you want an exact match it's it's up to you how you want to manage it but the truth is that the base HTTP get in this case for API B1 users should always return a list never are not found never anything else at least when okay then we have the get by ID which should return always a by when when I get it done with an idea in front of the of the endpoint a users slash the ID it should return only two states which is not found if the entity that I'm looking for it doesn't exist or okay this is pretty basic it's pretty simple I think you have have all seen it everything becomes to be less less common in the front so yeah it is difficult I would recommend you to use a globally unique identifiers because there's still the vulnerability that imagine that the user has access for x or y reason to other users and for some now he can just scrap the data by just going one users one your users to users three that way and scrap all the data for users and that's not the best idea by using this there's no way to increment on that because they're unique and completely different from each other so that means that it's hard to access it's you avoid that vulnerability and that's why I would recommend you to use a global unique identifiers for your entities if you're making a new API then there is the head this is not pretty standard I've seen it and it's it's it's well used and it has its sense but well it it's up to you if you want to use it or if you need it for some reason maybe your ended it's too huge using the head and providing the ID the same way as you have the as you had on the get like users and Slash the ID you can manage to check the existence of a of an entity the HTTP TTP head cannot send about it you cannot provide a body on it it's not it's not possible if you try you will always get an empty or an error the HTTP head can only send the status code so what you do is that you check if the a requested user exists or the requested entity exists if it doesn't exist you send a not found and if it exists you send a no contact no content there no content um it represents that the sales was success everything is fine but I have no data to provide you I'm just telling you that everything is fine and that's a way to to see if an entity exists an entity is available um you can also use it for heartbeat purposes I've seen that the implementation too that it's used to check the availability of the API if you need to to be calling the API further that it's this is a pretty lightweight request it will it will never send anything else than the status so yeah you can use HTTP hit to validate the status of the full API and make sure they exist you can keep checking and if if you get something different that's not an old content then you show hey there it's not available then we have the post which is pretty known it's for creating you you get on the body The Entity that you that the user wants to create and then you have some validation one of it is that you can check if if the user can not create a that entity for because another entity is conflicting with it before by then by its name ID whatever and then you you need to return the the result conflict which is the code 409. with a conflict that represents that there is an entity already that has some properties of this entity and that means you cannot create it you send a shoe back and then the the UI can interpret this one thing that you should know is that you should you shouldn't send messages messages on the on your API don't send an error saying hey there is an existing user with this ID don't send that by sending a conflict that should be enough for the UI to know hey I receive a conflict let me show this message you shouldn't manage that type of self that's IUI a user interface thing your API should be a agnostic of languages or of literal verbal languages and agnostic to the to the front end the presentation shouldn't be a a rule of for your API they that means that you can have an independent team working on the UI and while you keep the standards on the API everything should be fine you shouldn't have translations you shouldn't have anything related to front-end interaction on the on the back end and that's why you should be using in a A enums or identify types instead of of literal strings or stuff there might be cases where you need it but it's not recommended in all ways because yeah literally your API should be agnostic to to its front in in all the ways so okay so we have the conflict which is when you have an issue with with other entity of the same type in the in the end point and then you have the created ad which is a specific response for when you're creating an entity and it has a a way to access the get by ID because literally what they created ad does is that it kinda redirects to the created ad and also provides a header with with the URL it doesn't really regret it because it provides a header with the URL that says hey here is where you can access the just created entity so it basically it just sends back the the get by ID URL that's how it should work you should manage yourself how what's the URL in this case in.net you use created that action you provide where is the get by ID the parameter that it requires and the entity and it just sends back the created ad that's the response for the Post don't send an okay don't send anything else it's a created ad because you're creating an entity makes sense right if the entity cannot be created for some reason any reason there is an issue on it then you send a bad request which means that hey you have a validation issue and there are request can contain details inside any details you want of the exception so the the front end can manage it normally you should be using a specific code a a code that you should specify on your documentation or if the the front end can just take the bad request and say Hey There was an issue but normally the validations the bad request you can send a code because okay you want to but normally the validation should be on the front end you should only say Hey you send me something wrong there I cannot save that but then the product should know why it's wrong because you should not know you shouldn't be sending stuff invalid stuff like you should validate it but you shouldn't set details because it should be obvious to the UI that you should send a really valid and useful entity and that should be under documentation what you allow and what you don't see so yes you send about requests and you can return an exception or evaluation exception or a code representing what was the issue but the the truth is that the whatever issue happening that's happening when creating or we're running the the method should be about request then you have the update the update has any specific behavior hey first you it needs to have the user ID on the front I know it might seem stupid and people don't like to add it but the standard is that when you have you have the user the ID on users slash the ID of the user that you want to update and then uh you get the user on the body and using that you update the entity so the put should be able to update the whole entity every single value on it and should normally receive the full body of the of your entity and replace every single one of the values inside so one thing that you need to check inside the put is that the user ID provided as a parameter it's the same as the user ID inside the user entity I know it doesn't make any sense because yeah who cares maybe you can ignore it but the standard is that if it's different then you should send about request it's for security purposes validation purposes it's another layer of validation that makes sure that no one takes your API and executes weird behaviors or scraping or looping behaviors um yeah send them out requests if the user parameter it's different than the than the one from the user ID that you provide but yeah you need to request for the the Israeli but it depends on you you can also like set up that replace it the user ID inside your well the entity ID inside the The Entity by this one you can do a lot of stuff but the basic implementation is that yeah if it's different then hey I cannot allow you you're sending me an entity that doesn't match with the ID that you're providing me okay then we have the basic stuff the same thing as the post that you can have a conflict verifying that hey that entity that you're trying to update if you update it I will get a conflict there is already an entity that matches your specification you send a conflict back and then there is the not found you check the ID provided the ID provided that's also another reason why you have this on top and I can you can also pick that uh take that out of the of the try catch or whatever and just check out without accessing The Entity provided on the body just taking the the parameter you check if that ID exists if if it doesn't then you send a note found hey you can now update something that doesn't exist ER if everything went fine the happy path it's to send and no content why are no content instead of the whole entity because why they need an entity they have already created it so they have the ID and they have sent you what you want to update and we tell you hey it's working so you don't need to provide the entity back they already have it if they provide it to you so it's it's more lightweight do you send an hour content it's a standard response for an HTTP put no content everything is fine which is the a success state that doesn't return anything on the body no content should it will never let you return something on the body you should never return anything on the value when you send out content that's exactly what it means no content so yeah we have the no content and then there comes the patch what is the patch the patch is the same as the put but it can be used to send partial data just if you want to update just one a property on your on your on your entity you should be using a patch I would not recommend it it's not pretty standard not everyone uses it it's I think it's for pretty pretty specific uh cases where you need this but yeah it's there and many languages doesn't allow you to use patch by default and if you use webdap and net it you will have issues using the patch but anyway the patch works the same has the same Styles as the book but it's just for updating partial entities you can update only two or three or whatever and a specific quantity of properties inside the entity it's for that then one that I think it's not here and I should add is the HTTP delete the most it's pretty simple it's almost the same as they get so we have the get and then okay I forgot the the method itself public the actual result delete by ID maybe ID you're sorry it receives the parameter of the entity that needs to be deleted and it doesn't send anybody on it it shouldn't be something about it why what we do is that okay and not found if the ID provider doesn't exist the item with uh it doesn't exist and no content which is our great friend to send to say it's everything went fine for this action but you don't send a body on it and you just delete your entity in this case it will be users hmm remove user and that should do it that's how the delete should work so with that we already covered every single method and what should be the responses but there are other stuff that you should be able to manage in your API something that that there are some so many ways to manage the inner Properties or of your entities you can have independent endpoints like for example my users have contact information inside you could you could have the contact endpoint and access that those children by the IDS that are in the user but there is also a way to just manage this in this way imagine that you have the user they get by user ID but you want to access the contact on it to get contact by user ID and then you provide the children that it's inside in this case contact and then what happens is that you have users then you select only one user by just providing the ID and Slash the child entity and then you send back the body of that child entity or it would be the same if you want to make a post to create the child entity or a put if you want to update the child entity only it's a way to manage it and you can have or you can have just independent endpoints both options are completely valid another thing it's just a accessing a specific properties that are not necessarily entities a is so they don't have a put they don't have a post they don't have a they can have a patch but it's not fully recommended but it's more for accessing explicit properties without requesting the whole body of the entity this is great when you have really big entities and you only need any specific part of it for example one really common use is that for imagine that you need to access the profile photo of the user then you use the dollar sign and set the name of the property which is profile oh my profile picture and then here you use access imagine what's let's say that the name did you send the file of the of that picture of the user this could be a property that is not available directly on the user a hidden property or something that it's that it that it's owned by the by the specific user ID that's provided there you can send files or a specific a type um reference properties for example in this case the profile picture can be a URL and you want to send directly the file to it but again it's completely valid if you do this um yeah that's how that's how you should manage that that type of stuff the the if you want to access direct properties it's not super standard there are many ways to manage that but I've seen this in many examples on many companies uh big companies like Microsoft do this and I've seen it in some apis from Amazon and Etc it seems like a good idea I don't like it it's ugly but yeah if you want to access any specific thing like a file or something you should you can use this and yeah that's the the basics of an API always there there there is other stuff like a specific headers for example if you want to send uh incomplete data or you're sending pagination you should send headers that said hey this is the total number of entities and I'm providing this I'm providing you only this quantity you can manage that using headers don't send a specific entity for it it's possible there's nothing there's no rule or standard for it but a a pretty clean way to use it to implement this type of stuff is to have headers that manage the pagination information from the from the back end to the front end headers for it and yeah I think that covers well a lot that what what we have this is a summary of what are the endpoints that you need and the responses they get entities they get everything should always return okay they get entities with the ID should send an okay with the entity or a not found if the entity doesn't exist the posts should in the happy path return uh created when it when it receives a body a conflict if there is accountable or entity and about request if if it's not valid or it has an issue on it a output or the patch receives the ID and should receive a body and in the happy path if everything went fine on updating then you send a no content if there there was an issue for example that it doesn't exist you send a 404 if it has a conflict at 409 and if something happened that that doesn't let you create or update a mean and then you send about requests and if you need to delete an entity you provide the ID and send a no content if everything went fine or are not found if the entity didn't exist that covers the basics and I think that's enough if you create an API with this standards every there's a lot of people that will understand it immediately and it will be a uh uh a really common implementation of an API that it will compete to this to a sign of most of the major projects of public apis that that you'll know this is great for even if you have a public or a private API and normally private apis can have you can have more Liberty like to use your own standards but for public API I would recommend you to use this type of way because at the end it's a pretty common way to implement it and there there are people that by use Pro by your standpoint they will know hey okay I can make an update I know I will not receive anything I will create I can work with it there are even some technologies in the front that you provide this type of apis with this structure and they will work natively because they know that they will receive exactly what is expected so yeah it seems like a pretty good idea to preserve this structure for your next API there you have it that's how you can create a well-designed API that it's easy to document and easy to implement if you like this video don't forget to press the like button it's down there comment if you have any doubt or you want to see something else or just just have an opinion on my way to explain stuff and don't forget to check out our videos we have a lot of stuff so that you can learn a lot of interesting stuff and so check them out and subscribe if you want to see more that was it for me have an excellent day or night or whatever and yeah happy coding

Channel: Hahn Software

Views: 576

Keywords: #C, TypeScript, Angular, .NET, dot net, JavaScript

Id: t_yzqLo2L6U

Length: 23min 30sec (1410 seconds)

Published: Fri Mar 24 2023