Want to build a good API? Here's 5 Tips for API Design.

welcome back to my channel I'm Derek Martin from codepopinion.com and here are five things you can do to make your API more evolvable over time your API is going to change it will evolve and you don't want to handcuff yourself so here are things you can Implement today to make it easier to change thanks to event store for sponsoring this video event store DB is a new category of operational database built for event sourcing cqrs and event driven microservices for more on events.db check out the link in the description so the first tip is where you're generating identifiers IDs it's typical if you're using a database and you have some Auto incrementing ID is that your database is actually the one generating it so we have a client make a request let's say we're placing an order we persist that data to our database and our database at that point is the one generating that ID let's say that order ID and then we use that and return it possibly all the way back or use it somewhere else so what's the issue with auto incrementing IDs maybe nothing depends on your environment your contacts but if you're in a distributed environment with multiple different database servers you could be generating the exact same unique identifier that same ID that could pose a problem if you ever want to merge data however is also an issue if you want to move work asynchronously that means generating that identifier farther up the call stack it could even happen at the client if it's trusted but as well as it could happen at the API level at that point we're generating that I that order ID it could be a uuid a grid that's what we're actually persisting to our database but this also helps when removing work asynchronously if we were returning that order ID back to our client if we were generating it with that Auto incrementing ID at our database that means it has to happen the full execution needs to happen if we're generating at our API level then we can actually return that ID and move that work asynchronously that means when we generate that order ID from our API we can then actually just place a message on our queue and then separately return that order ID and have our workers some separate process handle that message completely asynchronously and then it can persist into the database we haven't really necessarily changed functionality we're still our API still works exactly the same as it did to our client but we're moving that work asynchronous if you're working in a distributed environment or you need a scale and you want to move work asynchronously we're generating these IDs matters you need to push it further up the call stack but that's not the only tip for identifiers here's another one so the second tip is generating something meaningful as an identifier now some people refer to this as kind of human readable I'm really more referring to human understandable I don't mean human readable by kind of these silly identifiers that get randomly generated like smelly cat or whatever the case may be that doesn't mean anything I'm talking something that actually has meaning so to refer to that when you're creating that order instead of creating some good uuid that is just completely random or I guess should say doesn't mean anything to you it's at that point generating an order ID that's meaningful that when you're looking at you as an end user somebody working in the system can understand and that is valuable information to have at a glance so for example I live in Ontario Canada so c-a-o-n is the province maybe some other number that could be date related but generating some ID that's gonna be unique but it has information has a meaning to it yes that may be composed of other information but it's always really useful when you're looking at this to know maybe geographically there's a lot of different ways that you can kind of slice this data and still keep it unique and it will be meaningful with these first two tips the aren't blanket statements saying you should do this everywhere of course not if you're watching my channel you understand that I'm really about context where something serves and has value so these are just suggestions about if you're going to be distributed if you're going to have moving work asynchronously and you need to scale in certain areas or and in certain parts of your systems you can generate meaningful IDs that will help people at a glance looking at information apply it where appropriate tip number three relates to responses and understanding and providing the client information about what they can do if we look at this data related to you let's say it's an order okay I have order data I have like the when it was placed the total the status or the customer is great but what can I actually do with this order it's pending well sure as a developer that kind of design time when I'm building out my UI or whatever I'm doing with this API is well okay I'm looking at the documentation I'm trying to figure out okay here's all the different actions I could perform I can cancel an order for example but well when can I cancel an order well when it's maybe let's say only when it's pending if it's being shipped well or has been shipped you can't cancel the order so at design time when I'm actually writing this code as a client and client code a UI it's now I'm adding this logic based on the documentation but again things of all things change so how do we provide our API with information about what it can do in a lot of systems the actions that you can perform are based on the state of the system or your users permissions but a lot of it's based on what does the state of a system look like right now so because of that you know what the state of the system is in your response so can this order be canceled provide that a part of your response we have a list of actions here one of them is cancel order so we can provide the client back saying listen here's the actions you can perform based on the state of this order you can cancel it what this means is our client our end client our UI is looking for this particular key this name saying cancel order that's what it cares about if that exists then it knows it can cancel in order if this doesn't exist and know that it's not an estate and it may not provide some particular UI elements to even let you cancel an order so that means that we're providing back to the client via our API what it can and cannot do based off the state of the system that means that you won't have as much business logic or duplicated Logic on the client which you already have on the server anyways and I mentioned evolvability and that's really important here because things change when we look at this response again let's say we make some business change related to okay well before it was just that the status was pending but now it's if the status is pending and the order was placed within 15 minutes then you can cancel an order if we had this Logic on the client we'd be changing it on the server and the client but now we can just make this change on the server and not provide this action of cancel order if we've gone past that 15-minute threshold another really important aspect of this is that you no longer care about identifiers or Uris because you're not constructing them they're given to you at runtime so what I mean by that is because we're looking at foreign action let's say canceller this is the key we're not constructing what the URI is the server gave it to us it's completely opaque the URI is completely opaque to the client at this point it could have included the identifier in the actual route so like to tail us into the first stuff is that the IDS almost become irrelevant to you now in terms of generating them as well as constructing Uris you're not really thinking about it evolvability now routes can change this is what has to stay consistent about what this key is but the actual routes in the past for any of your apis can actually change no more bike shedding about URI structure if you have state and it's meaningful to the actions that can be performed provided back to the client the fourth tip is don't handcuff yourself in your response allow room to actually make changes that are going to be backwards compatible so as the example here I have a list of orders this is what I API returns that's it what happens if I want to add something to the root of this well that's kind of a problem I'm gonna have to completely change the structure if you're going back to tip number three related to hyper media and providing actions and other information you may want to do so if this particular API had searching functionality let's say by status well what are the statuses with this current structure I can't return anything else other than a list of orders rather what we might want to do is return instead of an array just an object that contains the statuses everything that you could actually search by and then the list of the orders just be thinking about in your response and this doesn't necessarily just be the root it's any type of element that you're returning is that really going to be what it is as the example with status do you really want to be returning a string here maybe there's something that's not a string that's not going to be the client might be using to kind of stringify things maybe this is actually an object with some type of identifier that identifies what pending is that's going to be very static rather than a string so just think about the structure the data that you're returning and don't handcuff yourself tip number five is using the language of your domain that people actually understand and not technical nonsense like factories adapters all these weird things or things that you may come up with your own terms when something in the domain would not even refer to it that way use the language of the domain some things are going to be crud I get it but in this case of an order it's not update order no it's canceled or that's what you're doing you're canceling an order it's not updating an order so capturing the behaviors of the domain using the terminology there is really critical and being consistent with it again you're creating an API yes for other developers so the r tech people but get away from the technical nonsense and focus on what are the actual capabilities what's the data related to this that you're actually returning that is makes sense within the domain now that may seem obvious and it is more common that people are naming entities nouns as things in the domain that may makes sense but what's less common is actually capturing explicitly the names of the behaviors of the capabilities that your system actually provides that are often a part of workflow and those should be exposed in your API and named appropriately I really do think these five tips will help you evolve your system without having to make breaking changes I mentioned earlier that a lot of this isn't just kind of blanket statements where you need to be doing this everywhere pick selectively where these make sense and where they'll help you in the future if you want to join my channel and get access to a private Discord server where you can chat with other developers about topics like this you can join my channel the links in the description if you found this video helpful please give a thumbs up if you have any thoughts or questions or other tips that you'd like to share make sure to leave a comment and please subscribe for more videos on software architecture and design thanks

Channel: CodeOpinion

Views: 155,033

Keywords: api design, software design, cqrs, software architect, api design best practices, api design interview questions, api design patterns, api design interview, api design tutorial, api design course, api design principles, api design system design, api design and development, api design mock interview, api design python, api design using swagger, api design tool, api design adn development, api design sytem design, api design and delevopment, api design adn delevopment

Id: HBH6qnj0trU

Length: 10min 56sec (656 seconds)

Published: Thu Aug 31 2023