What is an API and how do you design it? 🗒️✅
ฝัง
- เผยแพร่เมื่อ 15 พ.ค. 2024
- An API or application programmable interface is a software contract that defines the expectations and interactions of a piece of code exposed to external users. This includes the parameters, response, errors, and API name.
We discuss how to design an API and what it takes to make the design scalable, extensible, and easy to use. HTTP APIs are widely used in software systems. HTTP is a stateless protocol, and systems often expose APIs using it.
00:00 Who should watch this?
00:13 What is an API?
01:41 Best Practices
02:22 Naming APIs
02:43 Define Parameters
03:29 Define Response Objects
05:02 Define Errors
06:22 HTTP Endpoints
07:47 GET vs. POST
09:10 Side Effects
12:09 Pagination
13:51 Data Consistency
15:11 Thank you!
Recommended system design video course:
interviewready.io
Along with video lectures, this course has architecture diagrams, capacity planning, API contracts, and evaluation tests. It's a complete package.
References:
/ building-services-at-a...
swagger.io/docs/specification...
Designing Data-Intensive Applications - amzn.to/2yQIrxH
System Design Playlist: • System Design for Begi...
You can follow me on:
Facebook: / gkcs0
Quora: www.quora.com/profile/Gaurav-...
LinkedIn: / gaurav-sen-56b6a941
Atomicity means that operations must complete or fail as a whole unit. In case anyone was wondering.
That's proactiveness that most of the managers looks for
Also known as: the all-or-nothing property!
@Gaurav, we should not return list as a response to an API, and should return an object instead. that helps when we need to add a new variable in the response. In that case clients won't break.
Say in your example, in the future, if I wanted to add a new variable like "String resonseStatus" along with List, I can't really do that without making change in clients. But if I already returned an object, I could add any number of new variables to accommodate in the future.
That's a great point, thanks!
I don't totally agree with this approach. Yes, as an API definer, things will get easy for you. However, your consumer should still migrate to the new API version. By returning object as a response, you are saving yourself from changing the contract every time, however you are reducing the clarity of your contract and need to tell a lot in the documentation. I would prefer changing the API contract every time I make a backward incompatible change.
gud one, but I see Swagger is using list instead.....?
You make so much sense
I think there should not be any problem if we are returning JSON object or using GRPC
So happy I found this channel!!!!! This is the next level interview prep material. I was focusing on the main, most important topics to study, more language based questions then I started getting System Level questions and didn't have a good explanation until I started watching these videos. The funny part is that I knew most this stuff, but I just drew a blank when asked. I hope to get through the playlist before my next interview!
Welcome aboard!
Hi Gaurav - just to clarify the following
1. APIs can expose only "public" methods ( not protected or private methods )
2. it is a good idea to minimize payloads sent in request objects via POST ( use GET instead ), and sending the routing information or action information in the JSON request payloads makes for dirty APIs.
I think RESTful APIs should work on Resource (in this case Group). We use certain HTTP verbs (e.g. GET, POST, PUT) to manipulate that resource.
So the URL of API should be like this:
GET /api/v1/groups//admins
Notice the resources are in pluralize form (groups, admins, employees). So if we want to get a details for specific admin, we can just append the adminId as well. (GET /api/v1/groups//admins/)
Optionally API could expect pagination, limit from URL GET parameters as well... like (?page_no=2&limit=20)
PS: Also most people use version in the beginning of URL. e.g. /api/v1/.
Exactly what i was thinking. Use nouns instead of verbs while designing Rest APIs. The actions are already defined by the types.
Also field filter reduces the payload in response, that way caller can decide what he needs.
Saved me from commenting. 2nd that absolutely.
ABSOLUTELY WELL SAID! THAT'S WHAT I NOTICED, IT SHOULD HAVE BEEN USED NOUN INSTEAD.
Thank you for this video, Guarav. Extremely helpful and I love your explanations. This has been a great resource as I prepare for an upcoming systems design interview.
Loved the video... I really felt like i was talking to u and u were reading my thoughts as u were clearing all the doubts. Great One 👋👋
Thanks for explaining the application programmable interface. This content is helpful for understanding the structure of an API. Insightful and thought provoking😊
Hi Gaurav, you are brilliant at explaining tech stuff. Absolutely love your videos. Really appreciate it! Thanks a ton.
The best way to design an API for designers is to start with the foundation. The foundation is where most developers get it wrong, from my experience. Everything starts with the why. A simple yet crucial question that one should ask. The why for doing something, triggers multiple conversations that span the user journey, business objective, data contract, data governance, compatibilities, and lastly the use case. Another really good thing I have noticed with a well-defined API is that it also makes you understand if the procurement of data is truly vital or not, thus, helping in prioritizing API A over B. If this API is only relevant to a very low amount of stakeholders, do I really want to design it? The rest are just bells and whistles.
Hi Gaurav,
First of all a big thanks to you sharing these neat and clean, content rich videos.
It helped me a lot to clear some of the key concepts which I use on day to day basis.
Finally I wish you all the best and I would say "YOU GOT A NEW SUBSCRIBER"!!!😊👍
Wow wow wow, your way of speech delivery is too fluent, I just love that
Great video Sir as always! Thank you so much.
thank you so much!! 4 years later this is still so helpful! im glad i found your videos!
Thank you!
Really clear explanation - thank you! :)
Hey gaurav, great seeing your videos, Wish someone taught me during my interview days, I remember some design questions I was asked - URL shortener, Web crawler and proximity servers(Yelp). You should definitely do these, I personally ask a few when I interview :P
Thank you!
Your video is very helpful. Keep posting good content.
Great video again. Good to see discussion on consistency here. Couple of comments. If the data is huge and if we are going to use IP fragmentation, then typically it is transparent to the application developer. Also it might have been interesting to get your perspective on handling partial success in the API, say for setAdmins, it set admins for the first 3, the 4 user id does not exist/not member of the group, how does it signal error. Thanks
Hi Hemanth, the response can be a complex object, in which there is a list of objects. Each object carrying information about each user. Using this way, we can give information on processing status of d admin.
{
AdminsProcessingStatus:
[
{ ISetASAdmin : true, ActionTaken : ExistingGroupMemberSetAsAdmin/AddedToGroupSndSetAsAdmin
}
]
}
Nice video, with excellent communication. Keep up the good work. Appreciated !!
Good to see a বাঙালী teaching code 😊👍 subscribed 🤟🏻
the kind of clarity you have while explaining clears up the mess in my brain.. thanks gs
Happy to help!
Thanks Gaurav. 6:44 shouldn't it be called as "controller" rather "model" ?
Yeah I might have messed up the terms a bit :/
Hi @Gaurav,, Can you tell how it is different to make APIs for Web and for Mobile apps? Should we use mobile approach and assume "one size fits all " theory or should there be different API design approach for Web or Mobile ?
Just a small technical clarification.. the whole URL has components called URI - first part is the server address (mapped to a server somewhere using the IP address and port number), after that comes the individual context resources. Instead of model (the URI that comes after server address), let's say context for the actual resource. The next part(s) are the actual requested resources, which consist the name of the api method, and any parameters if present.
Thanks.. searching a lot for a similar thing from a long time
Some of the ideas are covered in "Clean Code" & "Clean Architecture", nice vid!
This guy is the real MVP!
As a Database Developer, I see similar principles and terminology applies to API design as well. As they say, the more you know, the more things seem the same. Cool video bro.
Even the design of this video is excellent -- like it's already at 1.5x Playback speed.
I went to speed it up, but then I realized that it was already perfect!
This is what I was looking for! Thank you!
Real value education ! Thanks bro !
In 39 seconds this boy explains "what is an api" in a way i wish my mentors had done.
KISS..
Awesome, I like it very much I appreciated. Wow the hint on fragmentation.
A very effective one.
Thanks Mr. Gaurav.
Bro you are too good...!!! Keep it up.. Will be waiting for you further videos..
There are only 2 types of explanation for complex Computer Science concepts in this world:
- The one you had in universities which you don't understand sh*t.
- The one provided by an Indian engineer on TH-cam that would enlighten you in 15 min.
Thanks a lot man !
Good explanation. I may use some of this logic explanation on my channel. Thank you
Awesomest Video! That's so insightful.
The one we've been waiting for
Loved it! Thanks a lot
Great video man. Is there more product design (API Design) videos out there? I wasn't able to find much.
As always, good explanation!
great explanation even though i know all of it...great going .....learnt some too
Can you please share a flask setup to create an API like Django, means to say URLs &. Views in separate files
@Gaurav, I really enjoyed this video and I feel like I learned a lot in short amount of time! Thank you for taking the time to create this valuable content!
Thank you 😁
You are very motivating. Best of luck for more challenges
Really helpful Gaurav! Thanks
Regarding how to solve the 'number of admins' changed, you can subscribe to group chat changes.
You can subscribe to 'participants changed' event same as 'new message' event and etc. You must not query admins if you have them up-to date all the time.
Api design always starts from defining the resource url. Then you move towards defining the api spec and so forth... its called model first or api first approach.
thank you so much for giving this video it is very usefull
Hi, thank you so much for your help! If possible, please can you make a video about the Lemke Howson Algorithm (Game Theory) and how to do all of the steps for two 3x3 payoff matrices. Would really appreciate your help in drawing out the triangle simplex diagrams.
Thank you. :)
Thanks for great video.
What is the difference between pagination and fragmentation.?
an API is just a function...wow such a beautiful straightforward definition. I was confused since a week and everywhere they were just saying the things like "it is an interface to connect two software systems", "it is a set of rules and protocols" etc. but no was saying actually explaining it in terms of programming.
But Gaurav sir, you just helped me to get through its heart as what it actually is at its core. Thank you so much for relieving my week's pain and confusion.
Since it is a function that only care about "what" that is, it hides the abstractions so I'm assuming that it is an higher level function which calls the specific part/module of the system to get the work done and once the tasks is done, it compose the response (generally as an object) and return it.
api isn't a function but an interface (at least not in java). They're like contracts written for achieving abstraction similar to abstract classes but their purpose is generally for abstracting functions. Read about interfaces to understand.
Hello Gaurav, could u please give me a link about the API fragmentation please? Cuz i can't find one corresponding to what you described. Thank you in advance. I really like your videos :D
What book do you refer for system design
?
Very well explained. Can you also have session to cover various types of API?
For breaking the record, starting to watch you again, full fledge! :D
Welcome back!
Thanks Gaurav, you’re the real deal 👍
😁
Wish you 100K Soon #GKCS
Keep up the good work
Thanks for the great vid!
I instantly subscribed you because how confident your voice is
Thank you!
You are doing a great job!!
Totally understood the thing with one sentence in the beginning
😁👍
Hi Gaurav, Can you please explain the fragmentation part . May be in a separate video
sen u are awesome bro
i want to design an api for my intern.How to do it?
what other suggestions u have that i should do apart from coding?
This is pure gem ❤
@Gaurav, it was a nice & Brief Explanation
Hi Gaurav. A software contract is translated in OOP as an Interface implementation?. Talking about side effect is related to functional paradigm. Is a good practice to mix OOP and functional programming?
Hi Gaurav, thank you so much for this explanation! I have a question regarding setAdmins, what should the API response return if the one of the members of the group (admins parameter sent as a request) are already Admin or all the entire list of members of members are already Admins. Should we return 200 response? 10:08
Gaurav, First of all, thanks for the wonderful videos you have put up for the show..... I request you to make a video on bulk action like adding million people to a group or sending mail to all existing users in one shot.... this is the feature we want to add to our product but not able to find an apt approach or sol for it......
Wonderful in details API design !! Would have been great to include Bulk APIs on large dataset as well.
Thanks!
I'll try and talk about this in a future video 😁
Love your videos. Just an idea, Would Secure REST API be a good Idea for a video ?
Thanks for the great video Gaurav. Just a suggestion that can you please add some reference links on the video link like you were adding in the system design series video earlier. It will be really helpful when we want to go more in-depth of the topic in consideration. Thanks once again
True, thanks! Doing that now.
excellent as always
Which one would be better approach... getting lots of information in a single call using joins or getting small pieces of information by multiple call of different apis? My main concern is server and database load.
Hi Gaurav
How about returning only the IDs / Names in the list from the ListAdmins API and having another API like GetAdminDetails which can return the entire object (considering the object is too large). Do you think this can be a fair approach. I know a lot would depend on the type of end users and how they want to use the APIs but in general sense what are your thoughts on this one?
What if we keep response processing on API gateway side and the rest on microservice? Any pros + cons? Thanks!
Hey Gaurav,
Nice explanation of good practices for API design and I totally agree with the thing nirupam pointed out . I see that many people down in comments of your videos often ask for content that you have previously completed. It is just a suggestion to start adding related videos' links to the description and calling them out through the video. You can also use overlay popups of youtube that other youtubers use extensively. Will just save you some redundancy in questions.
Thanks
Thanks Avneesh! You are right, I can put them up better.
They also need to make an effort though. If they can't Google search or read the video description before posting a comment, it's a hopeless cause of them :P
@@gkcs I am with you on that, just a little effort goes a long way for in depth understanding. Also depends a lot on one's curiosity and interest in said topic. But its mainly for your own convenience to reduce your effort of giving them a link everytime such a question arises.
@@sdfg204 True, thanks!
*Phenomenal video!*
good stuff gaurav, it was very well explained. the only thing is the speed. I had to bring it down to 0.75x and listen it. If you can adjust the tone fast and slow at times, it will go a long way
Hi Gaurav, can you make a video on Security: Oauth2, Jwt, OpenId, Saml, Basic, Digest, SSO, Social sign in. There are plenty on youtube individually but none has all these as a whole describing use cases and differentiating each other
Sometime in future :)
Nice explanation mate
Nicely explained helpful video ❤️
Great video. Please keep posting such videos.
Explained well....Also It would be great if you share some real time test case using any Rabbit MQ kind or Messaging platform!
Maybe next time 😁
@@gkcs Thnak You 😊
Thank you very much for the tutorial. Could you please add subtitle as well?
The sound quality has improved a lot, are you using a new mic?
Yup!
Cann''t we do streaming for big response , if client need all data ? I am doing such thing where i have to sent big list , adv i get is very less memory consumption and streaming help with i need to invent chunking of data
@Gaurav, when you described the handling of Large Responses, you talked about 2 things [i] Pagination, [ii] Fragmentation. Shouldn't we consider HATEOAS also as a viable option? It would make API more connected and take off the burden of a large response.
Also, in case if an API is designed to perform any Bulk Operation lets say import, then what should be the correct way to design it?
Correct me if i am wrong but pagination is the thing that comes with hateoas right?
why you prefer to use POST instead of GET for read call
Hi Gaurav
I like the system design content that you have posted. Want a help in one question. Suppose you have to integrate an external third party product with say google maps. What are all security feature/ ways you will implement and also explain how?
🎯 Key Takeaways for quick navigation:
00:28 📝 An API is a documented way for external consumers to interact with your code, specifying parameters, return types, and possible errors.
01:26 🚫 Misnaming APIs or adding unnecessary parameters can lead to confusion and poor API design.
03:26 ⚡ Additional parameters in API calls can be acceptable for optimization purposes, especially when performance is a critical concern.
05:31 🛡️ Design API errors based on common expectations and the responsibilities of your service. Avoid returning generic errors for all cases.
07:01 🌐 Plan the routing and actions of your API carefully to ensure clarity and prevent ambiguity in the API calls.
08:30 🔄 Avoid side effects in API calls; keep the actions focused on a single responsibility and ensure atomicity when necessary.
09:57 📦 Break down large responses using pagination or fragmentation to maintain efficiency and prevent overwhelming the network.
13:58 ⚙️ Consider data consistency needs; decide if perfect consistency is crucial or if slight delays or cached responses are acceptable for certain use cases.
Onwe thing i want to say gaurav we have certain functions to mitigate the large length of api id in php,how can we say that it is a bad attempt of calling parameters
Is there a need to differentiate 'groupDoesNotExist' and 'groupIsDeleted' ?
Naming is important.
So is competitive programming 👍🏻👍🏻👍🏻👍🏻
Please make videos on Micro Services Architecture.
th-cam.com/video/qYhRvH9tJKw/w-d-xo.html
th-cam.com/video/vvhC64hQZMk/w-d-xo.html
Good video. I would say that one form of parameter defining can be handled with function overload, like instead of a single groupId we can pass a list of groupIds and output is still same i.e. list of admins.
Yes, extensible design for most usecases.
It does become overkill at times though :)
U r right that it can be an overkill if not design correctly...
I have a request as well, if it makes sense then can u do a video series explaining the use of JWT's + Containerized API/Microservice + Msg Queues. An end to end authenticated containerized Microservice.
How can we not show the details in the url? Like the Id of a user.How to make it secure?
great explanation , really appreciated. i am not from api backgroud and never worked on any api dev. , i worked on aws services , snowflake , mongodb , DI tools. i have questions , scenario : 1) developer has created some web services to generate some reports in .net environment and calling the reporting services to get data from postgre sql database hosted on aws , now reporting data which displays in browser through reporting services are very slow . 2) so would like to know reason , is there any bottleneck at api web service / service call while fetching data from postgre sql materialized views . wanted to check on slowness of reports from web service point of view 3) if these reports are slow due to database performance that i can validate by doing some tuning , indexing , db partition . so want to check on api service call bottleneck if any possibility or any pointers can be suggested
thanks
Mangesh