Deep Dive into REST API Design and Implementation Best Practices

in 2000 Roy Fielding proposed rest as an architectural approach to designing web services since then rest apis became the standard but designing a rest API is still a challenge that many developers and teams tackle even nowadays it's very important to design rest apis properly beforehand so that we don't run into architectural problems down the road that can affect the whole infrastructure we also take into account commonly accepted conventions security performance and ease of use for API consumers and this is exactly what we're going to be diving into in this video in general I would summarize an effective API design with three common characteristics an API that is easy to read and work with hard to misuse and which is complete and concise by taking into account the points above first we're going to look at one of the important aspects of the API design which is naming when defining an API endpoint always make sure to use nouns to represent resources not verbs so in this example we're going to use items and employees instead of create items or for example get employees also when designing endpoints it makes sense to leverage logical grouping that is if one object can contain another object you should design the endpoint to reflect that it's good practice regardless of whether your data is structured like this in the database for example if we want an endpoint to get the orders for a customer we should append slash orders path to the end of the slash customers path also I would advise avoiding reflecting the database structure with your apis to avoid giving unnecessary information to attackers you could also go in the other direction and represent the end point from the order back to a customer with a URL such as orders slash for example 99 customer however extending this model too far can become cumbersome to implement a better solution is to provide navigable links to Associated resources one possible solution is using eight OAS which we're going to be looking into in a minute besides when defining the names for your endpoints use pluralized nouns for resources like items and employees instead of item or employee a resource has data and relationships to other resources a group of resources is called a collection just keep that in mind for example slash orders is a collection of orders right and slash orders slash 99 is a resource with information about a specific order one important tip though try to avoid have having complex URLs than collection resource then collection don't go deeper than that also as a general rule use hyphens to improve the readability of URLs for example inventory hyphen management instead of the underscore also don't forget to properly version your API why well imagine thousands of customers are already using your API and their applications are relying on it what if you change one little detail in the URL name or in the response well then all of these dozens of applications are going to start breaking this is not good luckily you can always easily add a version path to your endpoint for example V1 store and so on alternatively rather than providing multiple versions of URL you can specify the version of the resource by using a parameter within the query string appended to the HTTP request for example version equals 2. in the previous point we mentioned hate OAS hos makes it possible to navigate all resources without prior knowledge of the URI scheme each HTTP get request returns information to find resources related to the requested object through hyperlinks the response also includes information that describes operations available on each resource for example to handle relationship between an order and a customer the representation of an order could include links that identify the available operations for the customer of the order currently there are no general purpose standards that would define the proper usage of 8 OAS it's rather just there and you wouldn't stumble upon it very often so it's just good to know that this thing exists in case if you ever need it in the future our next point is crucial to have in every API the databases behind the rest apis can get very large so we shouldn't assume that we're able to return turn all of that information in one go therefore we need ways to filter items by supplying query parameters with specific key value pairs like last name value and age value you can extend this approach to limit the fields return for each item if each item contains a large amount of data similar to how you wouldn't want to fetch all Columns of the database for example you could use a query string parameter that accepts a comma delimited list of fields such as product ID or quantity obviously we also want to have a way to paginate our data meaning request specific chunks at one time not to bring our database or Services down by requesting all the data meaning we can accept the limit query parameter and return a number of results that was specified in order to paginate the results meaning receive the next chunk the user will have to supply an updated value for the start alongside the limit filtering and pagination obviously increase the performance of our queries so it's always good to keep those in mind additionally we can also allow specifying the fields to sort by in clear strings for instance we can get the parameter from a Polish string with a field that we want to sort the data for then we can sort them by those individual fields for example plus author or minus date published keep in mind that some older web browsers and web proxies will not cache responses for their quests that include a query string in the URI one important rule that many developers Miss is at importancy there's an interesting video covering the case of ubereats and how the customers were able to order bid pretty much unlimited food by making one of the endpoints non-ide important the code that implements the route controllers should not impose any side effects the same request repeated over in the same resource should result in the same state for example sending multiple delete requests to the same URL should have the same effect okay although the HTTP status code the new response messages made different that's totally normal the first delete request my return status code 204 no content while a subsequent delete request might return status code 404 but the processing logic should stay item potent as a tip make sure your controller methods are pure functions let's talk about async operations sometimes a post put patch or delete operation might require processing that takes a while to complete if you wait for completion before sending a response to the client it might cause unacceptable latency if so simply consider making the operation asynchronous just return HTTP status code 202 to indicate that the request was accepted for processing but not completed you should also expose an endpoint that Returns the status of the asynchronous request so the client can monitor the status by pulling the status endpoint also include the URL of the status endpoint in the location header of the 202 response if the client sends a get request to this endpoint the response should contain the current status of the request optionally it could also include an estimated time to completion or a link to cancel the operation if there is synchronous operation creates a new resource the status endpoint should also return the status code 3 or 3 after the operation complete in the 303 response include a location header that gives the URL of the new Resource as the product gets more complex a need for supporting partial responses in your rest API comes up large binary Fields like files or images may be included in a resource to improve response times and overcome issues with intermittent connections we need to enable the retrieve of these resources in chunks to do so the API should support the except ranges header for get requests of large resources this header allows partial requests for specific byte ranges of resource which can be submitted by the client application also consider implementing HTTP head requests for those resources a header Quest is similar to a get request except that it only Returns the HTTP headers that describe the resource with an empty message body a client application can issue a head request to determine whether to fetch a resource by using partial get request the content length header here gets the total size of the resource and the except ranges header indicates that the corresponding get operation supports partial content the client application can use this information to retrieve the image in smaller chunks then the first request fetches the first 200 and or 2500 bytes by using the range header the response message indicates that this is a partial response by returning in HTTP status code 206 the content length header specifies the actual number of bytes returned in the message body and the content range header indicates which part of the resource this is a subsequent request from the client application can retrieve the remainder of the resource just very similarly to pagination error handling there's no way we can miss this one to eliminate the confusion for API users whenever error secure we should gracefully handle these exceptions and return a proper error Response Code so that it kind of gives a clue to the developer how they can debug this issue error codes need to have messages accompanied with them so that the main Tenors have enough information to travel through the issue but attackers cannot use the Arrogant content to carry out a text like stealing information or bringing the system down be very precise with the codes that you return for example anytime the body of a successful response is empty the status code should be 204. have you already watched my video on authentication if not I would highly suggest watching it first but here are the basic Milestones that every rest API should consider for the basic security first of all using SSL or TLS encryption obviously also a normal user shouldn't be able to access information of another user they also shouldn't be able to access data of admins we're going to talk about the concept of ACLS in the future videos also track clients and Implement throttling to reduce the chances of Dos attacks last but not least it's worth mentioning open API formerly known as Swagger which is an open source standard for describing documenting and visualizing restful endpoints it allows developers to define the structure endpoints request response formats and other important detail of an API so I would highly suggest using it as pretty much every other rest API out there I really hope you like this video and learn something new for yourself today and if you did please don't forget to subscribe to be notified whenever a new video is out and I will see you in the next one

Channel: Software Developer Diaries

Views: 40,599

Keywords: software development, software developer, programming, software engineering, javascript, web development, coding, rest api best practices, rest api design, rest api interview questions, rest api explained, rest api spring boot, rest api architecture, rest api bascis, rest api course, rest api crash course, rest api complete tutorial, rest api development, rest api endpoint tutorial

Id: 7nm1pYuKAhY

Length: 12min 1sec (721 seconds)

Published: Sun Jul 30 2023