What is an API and how do you design it? 🗒️✅

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:

Along with video lectures, this course has architecture diagrams, capacity planning, API contracts, and evaluation tests. It's a complete package.

References:

You can follow me on:

[nirupam]

@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<Admin>, 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.

[smithmarta]

Atomicity means that operations must complete or fail as a whole unit. In case anyone was wondering.

[haciendadad]

So happy I found this 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!

[harisridhar]

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.

[sidharthk.burnwal]

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 👋👋

[highmountdigital]

Thanks for explaining the application programmable interface. This content is helpful for understanding the structure of an API. Insightful and thought provoking😊

[bookbanshee]

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.

[nehascorpion]

Hi Gaurav, you are brilliant at explaining tech stuff. Absolutely love your videos. Really appreciate it! Thanks a ton.

[itsmainakmukherjee]

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"!!!😊👍

[gerryramosftw]

thank you so much!! 4 years later this is still so helpful! im glad i found your videos!

[rohanpandey]

Wow wow wow, your way of speech delivery is too fluent, I just love that <3

[sonalkumar]

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

[HemantKumar-hcvv]

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

[dhruvesingal]

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.

[nasimkaiser]

Good to see a বাঙালী teaching code 😊👍 subscribed 🤟🏻

[radhikagadve]

the kind of clarity you have while explaining clears up the mess in my brain.. thanks gs <3

[raghavchawla]

Great video Sir as always! Thank you so much.

[sonugupta]

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.

[mohanrajsenthilnathan]

Thanks Gaurav. 6:44 shouldn't it be called as "controller" rather "model" ?

[rahulprajapati]

Your video is very helpful. Keep posting good content.