What is an API and how do you design it? 🗒️✅
Vložit
- čas přidán 1. 06. 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.
Thanks for explaining the application programmable interface. This content is helpful for understanding the structure of an API. Insightful and thought provoking😊
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.
Hi Gaurav, you are brilliant at explaining tech stuff. Absolutely love your videos. Really appreciate it! Thanks a ton.
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.
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 👋👋
Wow wow wow, your way of speech delivery is too fluent, I just love that
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"!!!😊👍
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.
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.
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
}
]
}
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.
Good to see a বাঙালী teaching code 😊👍 subscribed 🤟🏻
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!
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 CZcams that would enlighten you in 15 min.
Thanks a lot man !
Great video Sir as always! Thank you so much.
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......
Some of the ideas are covered in "Clean Code" & "Clean Architecture", nice vid!
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 ?
thank you so much!! 4 years later this is still so helpful! im glad i found your videos!
Thank you!
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.
Your video is very helpful. Keep posting good content.
Nice video, with excellent communication. Keep up the good work. Appreciated !!
Really clear explanation - thank you! :)
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.
the kind of clarity you have while explaining clears up the mess in my brain.. thanks gs
Happy to help!
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.
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!
Thanks Gaurav. 6:44 shouldn't it be called as "controller" rather "model" ?
Yeah I might have messed up the terms a bit :/
Thanks.. searching a lot for a similar thing from a long time
You are very motivating. Best of luck for more challenges
Bro you are too good...!!! Keep it up.. Will be waiting for you further videos..
In 39 seconds this boy explains "what is an api" in a way i wish my mentors had done.
KISS..
This is what I was looking for! Thank you!
Awesomest Video! That's so insightful.
Awesome, I like it very much I appreciated. Wow the hint on fragmentation.
Can you please share a flask setup to create an API like Django, means to say URLs &. Views in separate files
Great video man. Is there more product design (API Design) videos out there? I wasn't able to find much.
Good explanation. I may use some of this logic explanation on my channel. Thank you
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
great explanation even though i know all of it...great going .....learnt some too
Really helpful Gaurav! Thanks
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.
Very well explained. Can you also have session to cover various types of API?
Loved it! Thanks a lot
The one we've been waiting for
@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 😁
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 please explain the fragmentation part . May be in a separate video
Real value education ! Thanks bro !
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. :)
This guy is the real MVP!
A very effective one.
Thanks Mr. Gaurav.
As always, good explanation!
Wish you 100K Soon #GKCS
Keep up the good work
thank you so much for giving this video it is very usefull
You are doing a great job!!
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?
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 😁
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.
What if we keep response processing on API gateway side and the rest on microservice? Any pros + cons? Thanks!
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
very nice Sen Sahab.
excellent as always
Thanks for the great vid!
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?
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!
Thanks for great video.
What is the difference between pagination and fragmentation.?
@Gaurav, it was a nice & Brief Explanation
Great video. Please keep posting such videos.
great video. very useful information.
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 :)
Nicely explained helpful 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?
*Phenomenal video!*
Nice explanation mate
@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?
@Gaurav one suggestion I have is and maybe it's a very important part of API design is that the objects which the API returns should be different from the actual backend objects. The reason this is very important is because if you decouple these 2 things, its easy to change something in the returned object without actually modifying the underlying business object. Also can you please add a video on how pagination is done?
That's a good idea, something I have seen in my experience :)
And I'll get to pagination in future videos :)
Can data transfer objects (DTOs) be used for this decoupling of objects. In C# context
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?
YOur Channel is Awesome. Thanks for such Videos!!! :)
I instantly subscribed you because how confident your voice is
Thank you!
Thanks Gaurav, you’re the real deal 👍
😁
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
Totally understood the thing with one sentence in the beginning
😁👍
This is pure gem ❤
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.
The sound quality has improved a lot, are you using a new mic?
Yup!
Thank you very much for the tutorial. Could you please add subtitle as well?
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
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 😊
For breaking the record, starting to watch you again, full fledge! :D
Welcome back!
Nice summary
Naming is important.
So is competitive programming 👍🏻👍🏻👍🏻👍🏻
How can we not show the details in the url? Like the Id of a user.How to make it secure?
You are awesome mate!!!!Love your videos
Thanks!
good explanation!