YT YouTube2Text

YouTube2Text → Transcripts → API Design and Architecture - Backend Engineering Intro (1 Hour)

API Design and Architecture - Backend Engineering Intro (1 Hour) — Transcript

by Caleb Curry · 8,377 words · 1,272 segments · language en · Watch on YouTube

Open in transcriber Summarize with AI Download SRT/VTT

Full transcript

0:00Hey, what's going on everybody? It's
0:01Caleb and welcome to your video on API
0:03concepts, design, and architecture. I'm
0:05really excited for this because this is
0:06the start of a series of videos on
0:08application development, backend
0:10development, API development. We're
0:12going to talk about a lot of concepts,
0:13but we're also going to follow up with
0:14hands-on exercises, and building out
0:16applications. So, first thing I wanted
0:18to mention is you'll want to check for
0:20the playlist link so you can watch
0:22through all of these videos. Now, this
0:24is a pretty long one. It's going to set
0:25the foundation. So, there's a couple of
0:26things I want to get out of the way at
0:28the beginning. So, I already mentioned
0:29the playlist, but I also want to mention
0:32the notes. I have extensive notes for
0:33this lesson and some of the upcoming
0:35lessons as well. So, you will want to
0:36check that out. I'll have a link down
0:38below. So, those notes act as a
0:39companion for these lessons. It'll have
0:41everything we're talking about,
0:42different code examples, references, and
0:45additional information that'll go along
0:46really well with these lessons.
0:49The other major thing is that some of
0:50these lessons will be concepts, some of
0:52them will be hands-on. You definitely
0:54want to follow up the concepts with
0:56hands-on material so you can solidify
0:58what we're talking about here. It's very
0:59critical that you follow along and
1:00actually build APIs so you know how to
1:03take what we're talking about here and
1:04apply it to the real world. And then the
1:06last thing, this isn't really an
1:07advanced series, but we're not going to
1:09start from the absolute beginning. So
1:11we'll introduce APIs without much prior
1:14knowledge, but if you need additional
1:15computer science principles,
1:18I have a fundamentals course which I'll
1:20have a link down to below. This is not
1:22mandatory, but if you find that the
1:24material here is going a bit fast, I'd
1:25recommend you go through that first. Oh,
1:27and one last thing, timestamps.
1:34We're going to cover a lot of
1:35information, so you'll want to use the
1:37timestamps available on the timeline or
1:38in the description to jump to whatever
1:40section you need. This will be handy if
1:42you want to reference certain sections
1:43later, or if you don't get through the
1:44full lesson in one go, you can jump back
1:46to where you left off. So, a while ago
1:48here on YouTube, I did a REST APIs in
1:501hour video, and I think this was a
1:52pretty good introduction, but this
1:53video's focus is going to be a bit
1:55different. First, we're going to go in
1:56more depth. We'll cover the same
1:58material with a lot of additional
1:59information and cover more material in
2:01this lesson because this is going to be
2:03dedicated to just all of the API
2:05concepts you need to know to be a
2:06software engineer. We'll talk about the
2:08different types of APIs. You might be
2:10coming here looking for REST API
2:11information, which is the majority of
2:14what we're going to talk about, but
2:15there are other API types as well. So
2:17we'll talk about how REST APIs are
2:18different than these other types.
2:20Additionally, we're going to bring in
2:21more system design concepts.
2:26So this gets into a little bit more of
2:28dealing with different servers and how
2:30to architect your API in a way that it
2:32can be scalable. So we want to build
2:34scalable systems
2:41that can support many many users. So, if
2:44you're just getting started, some of
2:45these things you might not worry about
2:46because you're just trying to build your
2:48first API. We're going to do that, but
2:50then we're going to go deeper and talk
2:52about more stuff you should know. We'll
2:53also talk about pageionation,
2:55authentication, versioning, and various
2:58other intermediate and advanced topics
3:00when it comes to building out
3:02applications. So, I'm very excited for
3:04this video. Consider this to be the
3:05foundation
3:08that you're going to build the rest of
3:10your knowledge on when it comes to
3:13application development and APIs. So, I
3:16want to introduce you to everything you
3:17need to be successful. So, we're going
3:18to cover a lot of different things in
3:19this lesson. By the end of this video,
3:21you're not going to be an expert on
3:22everything, but you'll have a much
3:23better idea of everything you should
3:25know, and we'll continue to discuss all
3:27of those different topics in future
3:29lessons. So, let's first start talking
3:31about what an API is, what it stands
3:34for.
3:38So, this stands for application
3:40programming interface.
3:43And this allows us to build applications
3:46that talk to each other.
3:51So when you hear the term interface, you
3:53should think of the surface area of
3:56potential interactions for an app. So
3:58let's say we build this app here.
4:02This app might work with a database and
4:04do all these complex things.
4:06But we don't just give everybody access
4:08to the database. We give specific things
4:11that the user can do. For example, we
4:13could get some data or we could delete
4:14some data. And these different things we
4:17can do that concept is called an
4:19interface. And it allows us to interface
4:22with other applications. So we might
4:24have a different app over here.
4:26And we can interact with app one from
4:29app 2 because app one has an API.
4:34So these two apps could be two
4:36completely different apps. For example,
4:37I might be building some calendar app
4:42and I'm using Google Maps API.
4:46Basically asking, hey, how long would it
4:48take to get to my appointment? And the
4:51API gives me back a response.
4:57So basically, I just enhanced the
4:59functionality of my app by using some
5:01other apps API. This is a very common
5:04structure. Another very common structure
5:06is instead of using a completely
5:08separate API, I might actually split my
5:10app out into backend front end. So
5:14logically the same product or same
5:17purpose but two separate code bases. And
5:20this front end will just make API
5:22requests to my backend. This backend can
5:25then grab data from the database or make
5:27sure that whoever is asking for this
5:29information is authorized to ask for
5:31that information. So we're not just
5:33giving data out to anybody. And then
5:34once the back end does all the
5:35processing and whatnot, it sends the
5:37data back to the front end. The front
5:40end can then display it all pretty and
5:42cute on a web page. So this is the other
5:45major structure that you will see APIs
5:47for in this situation. You can still
5:49think of these as two apps. We have a
5:50front-end app and a backend app. They're
5:52just working together to provide a
5:55single product.
5:58So this is different than if I use some
5:59third party API to enhance my app's
6:02capabilities. But both of these are
6:03possible. Doesn't really matter. The
6:05whole idea with an application
6:06programming interface is you can do
6:07whatever you want. Basically, we create
6:09an app and we expose different
6:12capabilities to the outside world to
6:14interact with our app. So that is the
6:16general idea around APIs. So this is
6:18what we're building, right? But there
6:20are actually different types.
6:23So these types of APIs, that's what I
6:25want to talk about now. The main one
6:28we're going to start working with is a
6:30REST API. So, R S where you might see
6:33RESTful
6:35which is an API that follows REST
6:37principles. So, that's probably the
6:39first thing you should become familiar
6:41with, but we're going to compare it to
6:42some of the other options out there. So,
6:44let's talk about the types of APIs. And
6:47I'm going to talk about some of the most
6:48common ones, but there are other ones
6:50I'm sure. So, the first one we just
6:52mentioned
6:56would be a REST API. REST stands for
6:59representational state transfer. So it's
7:02some way to transfer state between apps.
7:05REST will use HTTP. So we'll be able to
7:07do this inside of a browser and it works
7:10with JSON. JSON is an object notation.
7:13So this describes how we structure the
7:15data that we send over the line. Now
7:17another one you might hear is SOAP.
7:21Now I never use SOAP. My temptation to
7:23make some stupid joke about real world
7:25soap is unbearable. This is an
7:28alternative to rest.
7:35This was used a lot more in earlier
7:38applications. So you might see this for
7:39legacy systems
7:42or enterprise systems.
7:46A big difference with these SOAP APIs is
7:48that they use XML, which is you can
7:51imagine JSON, but 10 times more annoying
7:54and difficult to work with. Then you
7:56have XML. So if you're building a new
7:58system, I wouldn't use SOAP, but you
7:59should definitely be familiar with it,
8:01at least an idea. So if you do come
8:03across a SOAP API, you're not like, "Oh,
8:05what's this?" That'll be important if
8:07you're building a new system that
8:08integrates with an old system. that old
8:11system might not have a REST API and you
8:13might need to use SOAP. Even though
8:15you're building a new system, the
8:17interaction with the old system, you
8:19need to adhere to the API of the old
8:22system. So say this is the old system,
8:24you might be making new upgrades and
8:26instead of completely replacing
8:29the old, you might just make a new app
8:34that integrates with the old app
8:37providing new features or new interfaces
8:40for users.
8:42But for this you might need to use
8:44whatever the old app uses for
8:46interaction. So that might be a SOAP
8:48API. Next up we have GraphQL.
8:53Now, if you're familiar with databases,
8:55you might be familiar with SQL. And this
8:57is structured query language. GraphQL
9:00works in a very similar way, but it's
9:02not to interact with a database
9:03directly. Rather, it's to interact with
9:05a backend.
9:07So, in this situation, instead of
9:09exposing multiple endpoints,
9:17this would be the traditional rest
9:18approach.
9:27What we'll do instead is we'll just
9:29create a backend that is a very pretty
9:31back end that has one GraphQL endpoint
9:35that the front end can connect to
9:39or the other app can connect to and then
9:41the front end here does the decisions on
9:45what it wants.
9:49So you can think of it as the front end
9:50providing a query to the back end and
9:52then the back end provides the
9:54appropriate response. So this is a
9:56really common thing. Usually I would
9:58recommend people learn this. So if you
9:59already are familiar with REST, you
10:01should probably get some experience with
10:02GraphQL. However, if you're brand new, I
10:05would recommend first learning REST.
10:06Next up we have GRPC.
10:10Now you may have heard of RPC before,
10:12which is remote procedure call.
10:16You can think of this as a way to
10:17execute things
10:21on the back end. But when we prefix it
10:24with G, this is a specific protocol, the
10:27Google RPC protocol. Now, many people
10:30are going to say that this G stands for
10:32Google.
10:34However, I think officially this stands
10:36for
10:41GRPC, remote procedure call.
10:45So, it's just a recursive acronym.
10:47You'll see this quite commonly in
10:48different technologies.
10:50But ultimately, when you see gRPC, you
10:52can think Google remote procedure call.
10:55And this is a specific type of API that
10:58uses something called protocol buffers
11:00or protobuffs.
11:02So instead of XML or JSON, we'll have
11:05protocol buffers.
11:08So this is an approach to serializing
11:10data that's very effective. It it
11:12reduces the uh size of the data as much
11:15as possible, allowing for very fast
11:17transfers between apps. This is really
11:19common for micro service architectures.
11:22So let's say instead of just having a
11:24front end and a backend, you might have
11:26all these different components that
11:28interact with each other
11:30and all of these work together to
11:32provide
11:34the architecture for some app.
11:40This generally is called a micros
11:41service architecture and using
11:43protobuffs is pretty common for this for
11:45that cross app communication although
11:47not required. You could just use a rest
11:48api. So with this you will have files
11:51that are of the prototype
11:55not prototype prototype and these
12:00define a structure for the types.
12:07So every single app can use these proto
12:10files to establish the structure of the
12:13data in their individual apps whatever
12:16language that might be. So this is
12:18really great working across multiple
12:19different languages. We can define all
12:21of the types with these protoiles and
12:24there's ways to transfer from a protoile
12:27into a certain type for whatever
12:29language you're working in. Now I would
12:30say those are the main four you should
12:32be familiar with. You can also use
12:34things like websockets to interact
12:36between apps. So you can build a
12:38websocket API
12:44and a websocket is a birectional
12:48channel to communicate.
12:50So if we have a backend and a front end
12:54or two apps, they don't have to be
12:55backend front end. We typically with a
12:57REST API, we'll make a request to the
12:59back end and then the back end gives a
13:01response. But with websockets, the
13:03backend can also send data directly to
13:06the front end without a request.
13:08Basically, the way this works is the
13:10front end opens a connection
13:13and then that connection is maintained
13:20and the communication can then happen
13:22from either direction as long as that
13:25connection is maintained. This is really
13:27common for real time applications.
13:32So if something happens on the back end
13:33and we need to immediately tell the
13:35front end, then you could say this is a
13:38real time app. For example, a
13:40communications app such as chat or
13:44notifications
13:48and so forth. Anything where the
13:50communication is initialized from the
13:52back end. But do keep in mind that the
13:54front end can also send data to the back
13:56end as well. So here are some of the
13:57other types of APIs. You can look up
13:59others if you want to know more
14:00information. These are some of the
14:02things I'm hoping to cover here in this
14:05playlist or on YouTube.
14:08So, if you're interested in building
14:10some of these things, you'll definitely
14:11want to hit that subscribe button,
14:13follow along for the journey. And now
14:15what I want to do for the rest of this
14:16video is zoom in on this one here.
14:22REST APIs or as I mentioned you might
14:25see restful APIs.
14:29Once you have this down, you should be
14:31pretty competent in cross app
14:34communication and then picking up these
14:35others is going to be a whole lot easier
14:37because you understand the principles.
14:38Now the actual way you do it is going to
14:41be different. So there's some stuff
14:42we're going to talk about that's
14:43specific to restful APIs. So
14:45specifically, we're going to have
14:48different methods we're going to talk
14:49about. We're going to have a variety of
14:52end points.
14:56We're going to have status codes,
14:58response codes,
15:02and we're going to be working with JSON
15:05data. So if you're not familiar with
15:07JSON, it's really, really simple. I'll
15:09show you a very basic example right
15:10here. right now, right at this moment.
15:14Not going to delay. Just going to show
15:16it to you. Okay, it's going to be right
15:18here. So, JSON stands for JavaScript
15:20object notation.
15:23It looks very similar to an object in
15:25JavaScript. If you haven't used
15:26JavaScript though, it's no big deal.
15:28Basically, you're going to open the
15:30object with a curly brace. Then, you're
15:32going to have a series of attributes.
15:33These will be quoted such as name
15:37and then a colon and then the value
15:42and then a comma
15:45and then another attribute quoted
15:49and then a value such as 30. In this
15:52case it's not quoted. This supports
15:54different types here. So we can use a
15:56string which we showed with Caleb. We
15:58could use a number.
16:00We can use a boolean true or false.
16:03We can have nested objects.
16:06That's an important thing here. We can
16:07structure objects inside of other
16:09objects.
16:11And we can have arrays. I think we can
16:13also have null as well, which you can
16:15count if you want. So if you have an
16:18attribute and you specifically want to
16:19say there's no value for that attribute,
16:24you can use null. Notice that there's no
16:27quotes here. That would be a string
16:29containing null. It's just null, the
16:31keyword. Now, if you're coming from
16:32JavaScript,
16:36you might notice some similarities, but
16:38within JavaScript code, you don't have
16:40to quote the attributes. And you can
16:42also use different types inside of an
16:44object within JavaScript. So, for
16:46example, you could use a date
16:50or a function
16:54or undefined.
16:56These things are not supported in JSON.
16:58So it's not a one one two JavaScript
17:01objects. So I wouldn't even really
17:03strongly associate this with JavaScript.
17:05I would just think of it as JSON with
17:07key value pairs surrounded by curly
17:09braces. Okay, so we have a pretty decent
17:11understanding of the structure of our
17:13data. How do we use the structure to
17:15build an API? What does a REST API look
17:17like? Well, some of the things we just
17:19mentioned, we'll have a method
17:24for example and these are written in all
17:27caps. Get this is an HTTP method. So,
17:30REST API is built on top of the HTTP
17:33protocol. So, with that, you'll have an
17:35HTTP method. Get is a very common one.
17:37This is used to retrieve data from a
17:40server. And when you go and visit a web
17:41page, you're actually making a get
17:43request, even if you're not working with
17:44APIs directly. And then you'll typically
17:46have some resource.
17:50So resource you can think of this as
17:53here. Let me give you a bunch of other
17:54abstract names. Entity,
17:59an item or some database record.
18:03This is basically the thing that we are
18:05wanting to interact with. So an example
18:08of this would be users.
18:10And that would be something that might
18:12give us back that same JSON structure we
18:15saw earlier where we have the person's
18:17name and their age. I'm going to go
18:19through the example of comments posted
18:21on a website. So this could be a social
18:23media, it could be whatever you want,
18:25anywhere that you can post a comment.
18:29So let's say you have a video
18:33and people can post comments below.
18:37We need a way to be able to retrieve
18:39this information from the backend and we
18:42don't have direct access to the
18:43database. So it's going to look like
18:45this. We have the backend.
18:48The backend stores that data in a
18:50database.
18:52We make a request for comments
18:57and then that backend formats the data
18:59as we need and gives it to us
19:03in JSON.
19:05Once we have this JSON data, we can work
19:07with it on the front end to format it
19:09and make it look nice to the user, which
19:12is how we end up with
19:15a web page with the post and then the
19:19comments below it. So that's the general
19:23workflow. Then when a user goes in here
19:25and maybe posts a new comment, this is
19:28going to follow that same pattern, but
19:30now it's going to make a request to the
19:32back end with a different method. So
19:34instead of a get request, we're going to
19:37do a post request. All right. At this
19:40point, you have a pretty decent idea of
19:41what a REST API looks like or how you
19:44interact with it. You have a method, you
19:46have some resource, and then you work
19:49with JSON. That's how you communicate
19:51back and forth. So how do you grow this
19:53to then a collection of different
19:55endpoints? So that's a word you should
19:57know. You can think of the end point
20:02as a combination of the method
20:06plus the path.
20:09The path here is basically a URL
20:12describing what resource you're trying
20:15to interact with or collection of that
20:18resource. So let's take a look at an
20:21example with comments. We're just going
20:23to write out all of the URL structures.
20:26And you can think of these as basically
20:30the different interaction points or
20:32interface
20:35to your API.
20:38So these will all probably be prefixed
20:40with slash. So you start with a slash,
20:42but you're going to have something
20:43before that slash, which will be
20:45whatever your base URL is, the backend
20:47API URL. So it might be something like
20:50mysight.comi
20:52[Music]
20:56and then it's pretty common to have some
20:58version in here. So you might be on v2
21:00or you might be on v1. basically a way
21:02to create different API versions. Then
21:04you will have the resource
21:08and then if you're working with a
21:10specific instance so not just all of the
21:12comments but one comment in particular
21:15then you can pass in an ID.
21:19Now this is substituted in.
21:22So when you visit the web page you're
21:24not going to actually put ID. You'll put
21:26in a value like five or 105 or whatever
21:28the ID is for the element the resource
21:31you're trying to work with.
21:34So the way you describe that this is
21:36substituted in. You might see something
21:38like brackets ID or you might see colon
21:42ID. The exact notation is irrelevant and
21:45every framework is probably going to
21:46have a slightly different structure. But
21:49the idea is that we need to indicate
21:50somehow that the user provides in an ID
21:53to access that element. So for us, we're
21:56just going to use curly braces ID.
21:58However, there are some architectural
22:00designs with the way you structure your
22:02URLs and your code around the resource.
22:06So, in this situation, let's say we are
22:08working with comments.
22:12Do you work with comments directly or do
22:15you always work with comments through
22:18something else such as the actual post?
22:24So you might have post
22:27the ID of that post
22:31and then get the comments for that post.
22:37This is a different structure where you
22:39now think of comments as bucketed
22:41underneath a different resource in this
22:42case posts. And usually this is going to
22:45be plural. So posts, id comments. So
22:49we'll talk about some of these ideas of
22:51nesting data as there are some
22:54alternatives where you can use URL
22:56parameters to query or filter data
22:59differently. So we'll look at that soon.
23:01But for now let's go with this approach
23:02here where we are working with a parent
23:06resource. We access a specific post with
23:09an ID and then we can grab all of the
23:13comments for that post. So let's write
23:16out some example endpoints. We'll start
23:17with the method and because we'll often
23:19have the URL SL API potentially slv1 or
23:23v2 I'm not going to put that every
23:25single time. You can just think of that
23:26as copied on all of these. So all we'll
23:29have is slashposts
23:32slash
23:36id slash comments.
23:40So this is the endpoint for retrieving
23:43all of the comments on a specific post.
23:46So we have some video. This video has
23:48the ID of 1 2 3 and it has a series of
23:51comments down here. The API endpoint to
23:55retrieve this information
23:58would be posts 1 2 3
24:02comments.
24:04So this is the URL you would use to
24:06access all of the comments for the post
24:08with the ID of 1 123. Now the next
24:10method we're going to look at is post.
24:11This is how you add data. Now don't be
24:13confused because we're talking about a
24:15resource posts.
24:18This is referring to posts on some
24:20social media platform like a video post.
24:24Then we also have post which is an HTTP
24:28method that means to create. That's
24:30usually used to add new data. So when we
24:34come up here and we say post, we're
24:35talking about the method
24:38and we're going to create a new comment.
24:42So it'll be the same exact URL
24:44structure. The only change here is the
24:47method that we used. So the method is
24:49used to tell the server what we're
24:51trying to do. Because we're adding some
24:53new data, we will need to attach the
24:55comment
25:00data itself in the body.
25:05So when you make a request, you'll have
25:07headers and you'll have the body.
25:11So that's where the actual JSON goes.
25:16So when we get some hands-on practice
25:18with this, if you've never done this
25:19before, I'll show you exactly what I
25:20mean. So that's going to be important
25:22anytime we're adding new data because
25:24the URL itself doesn't give enough
25:26information. It doesn't say what the
25:28comment we're actually posting says. So
25:30we need to include the actual comment
25:32content and we do that in a separate
25:33section called the body. All right. So,
25:36you have a video post, you have comments
25:38on here, and we know how to get them
25:39all, but there might be a specific
25:41comment. And when you create this
25:43comment, that comment is going to have
25:45its own ID. Let's just say it's 321.
25:49Well, to access this comment, if it has
25:52a unique ID,
25:57we don't need the parent ID. We don't
26:00need to know what the video ID is. So we
26:04can access this without the nesting of
26:07the post. So it'll look something like
26:09this. Get slash comments
26:14slash
26:16id. So if we made that concrete it would
26:18be slash comments
26:21slash 3 2 1. And that'll give us the
26:24comment content.
26:27And most likely it would have the post
26:29ID as well as part of that data. So we
26:31could associate it with a certain post.
26:33So if we needed, we could use that to
26:35figure out what video it goes on. So
26:37let's just add some notes here. So this
26:39is to get all the post comments.
26:46Add a comment to a post
26:50and then grab a specific comment. Next
26:53up, the next method we're going to learn
26:55about is put. This is used to replace or
26:59update some data. So if we're going to
27:01edit our comment, we can use a put
27:03request. Again, for all of these that
27:04are working with a specific comment, we
27:06don't need the parent post. So we can
27:09just say comments
27:11slash id. So notice these are the same
27:14URL similar to get and post. The only
27:17thing differentiating them is the method
27:19used. So this will replace or update
27:26comment.
27:27Now there's another type of request we
27:31can make which is a patch request
27:34which works pretty similarly but there's
27:36some key differences here that you need
27:37to understand. So the URL will be the
27:40same.
27:45This is going to partially update.
27:48So what that means is with patch if you
27:50had some
27:52document
27:54and you had multiple things you wanted
27:55to change in it with a patch you could
27:57just select one of these things and
27:59change it.
28:01With a put request you will take the
28:03entire information make some changes
28:08and send the entire information back. So
28:10you're basically replacing the document.
28:13It's going to be the same idea here with
28:14comments. If we're using a put request,
28:17we need to take the full comment, make
28:19the changes, and then send the full
28:20comment back. With patch, we can
28:22selectively change attributes of that
28:24comment. So, this really only makes
28:26sense if a comment has multiple
28:29attributes. So we might have a comment
28:31ID,
28:34a post ID, the actual comment content,
28:39maybe it's a boolean whether this is a
28:40reply to somebody,
28:43maybe there's a boolean on whether it's
28:45a pinned comment. And basically with a
28:47patch, we could update any one of these
28:49attributes individually. But with a put,
28:51we're going to take all of the
28:53information.
28:56again we'll change some piece of it and
28:59then we'll give the entire document back
29:01replacing the old one. So logically
29:04we're still updating the data. The ID is
29:06going to stay the same
29:12but the way we're updating the content
29:14is by replacing it completely. So one
29:17very important thing about updates is
29:19that they should be item potent.
29:25And this is a fancy word to basically
29:26say if you execute that update multiple
29:29times, the end result should be the
29:31same. If we replace the document a 100
29:33times with the same information, we
29:35still have the same end result. And
29:37that's exactly why this comment ID has
29:39to stay the same because if we were
29:41giving it a new ID, we're creating a
29:42different comment every single time.
29:44This is important for accidental
29:46resubmissions.
29:49We could submit an update multiple times
29:57and that's not going to break anything.
30:00But if we did a creation, if we did a
30:02post multiple times, we're going to
30:04either get an error or accidentally
30:06create duplicate data. So a post is not
30:09supposed to be item potent. Now this
30:12attribute is something that you need to
30:14enforce in your code. So you can code
30:17these to do whatever you want. You could
30:19make a postdelete data. You can make a
30:21get update data. That's all up to you on
30:23the back end. But these are standards
30:25and a specification for a reason. People
30:27adhere to these because you can have
30:29implicit meaning behind these words. So
30:31when we're talking about updating data,
30:33it should be known to be item potent.
30:37So, we're not going to be replacing the
30:38ID of the thing we're updating. Next up,
30:41we have delete.
30:44It's pretty tough to figure out what
30:45this one's going to do.
30:49Again, it's going to be the same path
30:51because we're referring to a specific
30:53comment.
30:55And that will remove the comment. Now, I
30:57want to show you a couple more examples.
30:58What if we wanted to reply to a comment?
31:01In this situation, we would have a
31:02comment that in a way depends on another
31:06comment. So we would need to know
31:10information about the parent comment.
31:14Who are we replying to? So the way we
31:17would structure something like this
31:20would probably be a post because we're
31:22creating a new comment and then we would
31:24do slash comments
31:27slash id
31:30and then we could have a new path such
31:31as
31:33reply and this could reply to a comment.
31:39And the reason I wanted to write this
31:41one out is because I wanted to show you
31:43two possible different scenarios here.
31:45And either one is okay. So it's not like
31:48the way you do things is 100% set in
31:50stone. You can have design decisions
31:52about the way you structure your API. So
31:54what exactly am I talking about here?
31:56Well, we could now create a comment with
31:59this post or we could create a comment
32:02with this post. Basically, we need to
32:04get the parent ID from somewhere. In
32:07this case, we're getting it from the
32:08URL.
32:10In the case of this post request, we're
32:13not providing the parent ID here, right?
32:15We're providing a parent video that the
32:18comment's going to go to, but we could
32:20still create a reply here if we wanted.
32:23It would just be passed in the body. So,
32:24it might look something like this. The
32:26video was 1 2 3. And then the body would
32:29have
32:31the content of the comment
32:37and it would have the parent ID.
32:42So both of these could work the same
32:43way. In this situation, we're passing
32:45the ID of the parent in the URL 5 67. In
32:49this one, we're passing the parent ID in
32:51the body. Either one of these are going
32:53to need some parent to grab the ID from.
32:56So the only major difference is how you
32:57want to structure the URLs and whether
32:59or not you want this to be nested under
33:01posts or not. In reality, if you're
33:03making a comment reply, doesn't matter
33:05what post it's on because that parent is
33:08unique. Basically, we have a comment 567
33:11and we are creating a reply to it. We do
33:14not care what the parent post is. We
33:16only care about the comment we're
33:18replying to. Logically, it's going to
33:20get us the same result in the database.
33:22This one just has it unnecessarily
33:24nested under a post. Let's go with one
33:26more example which would be to get a
33:28comments replies.
33:30So this might be at slash comments
33:36slash comment id
33:40slash replies.
33:42Same idea here. We don't really care
33:44about what post it's on. All we need is
33:46the ID of the comment we're replying to.
33:48So one quick comment that I wanted to
33:49add here. I would consider each one of
33:51these a different endpoint. So we have
33:54eight different endpoints here. There
33:55might be some conflicting vocabulary
33:58that you run into. So for example, we
34:00could consider all four of these
34:04to be the same endpoint with the same
34:06URL and then just have four different
34:08method options. But I don't think that
34:10makes as much sense because these in my
34:12opinion are unique interaction points of
34:14our app. So even though they're sharing
34:16a path, logically I see them as
34:18different end points. I wouldn't get too
34:20caught up in the vocabulary for this,
34:22but that's just how I tend to think
34:24about it. But what you can say is you
34:26definitely have one path with four
34:29different methods. So all of these in
34:32code
34:34could point to a single function
34:39or it could instead go to four
34:41individual functions.
34:47This is a design decision that is
34:49irrelevant from the interface of the
34:52API. The way you work with the API is
34:54exactly the same. So all of this stuff
34:56gets into how you structure the code.
34:58And I wouldn't worry too much about that
34:59right now. It's just the way you
35:02structure your code. Do you have one
35:03function and then you check what the
35:05request type is the method or do you
35:08have four different functions each one
35:09being associated with the combination of
35:12the method and the URL for unique
35:16destinations. So when we get into
35:17implementation we'll see the differences
35:19here but for now I would just focus on
35:21what the API allows us to do. So this is
35:25our full interface of how we could
35:27interact with comments. We can continue
35:30to think of different ways of how we
35:31might retrieve comments. For example, we
35:33might want all of the comments from a
35:35certain user.
35:37In that situation, it would look
35:38something like this. Get
35:42slash user
35:46slash ID. And this ID always refers to
35:50whatever it is that came before it. So,
35:51the user ID and then we could have
35:54comments.
35:56We're still working with comments, but
35:57we're basically shifting the way we're
35:58thinking about comments. Instead of
36:00associating them under a post, we're now
36:02thinking of them by user. So, we're
36:05changing the bucketing. For a simple
36:06API, you probably don't worry too much
36:08about it. You know, maybe we have just
36:10this many ways to access comments. But
36:12for a complex API, there might be a
36:14large variety of different ways to
36:16retrieve comments. And remembering the
36:19nesting and the structure for this can
36:20get complicated. I'd say starting out I
36:23prefer this structure but I want to
36:25share an alternative which is basically
36:27the comparison of
36:32nested data
36:37versus filtering
36:42and this would be filtering just a large
36:44singular collection. So let's go through
36:47examples showing the differences of
36:49these because when you're designing your
36:50API, you want to know how you're
36:52structuring the API endpoints. This is
36:54also going to get into different ways of
36:56passing data. So this is part of the
36:58path,
37:00but you can also use URL parameters,
37:03query parameters. We're going to look at
37:04those as well. So we've already talked
37:05about nested data.
37:09Basically, when we want to access some
37:13entity but relative to
37:18a collection such as the post,
37:27we can structure our URL like this. And
37:29I don't know why I didn't finish writing
37:31comments, but it's going to look
37:32something like that. Now, for filtering,
37:34we just consider having one giant bucket
37:36of all the comments. And then we provide
37:38additional information to say which of
37:40those comments we care about. So we have
37:41our giant collection of all of our
37:43comments and then we say question mark
37:47then some attribute such as the post ID
37:50and then we set that to whatever the ID
37:52is we are looking for for the post. So
37:55this concept with the question mark this
37:56is called a query parameter
38:01or you might hear URL parameter.
38:06It's slightly different than putting it
38:09in the path. So you can see here we
38:11don't use a question mark here, but
38:13functionally it can be used to achieve
38:15the same results which is changing the
38:17data that we access. So we'll talk more
38:19about the differences between using a
38:20query parameter and using the path in a
38:23moment. But for the sake of this
38:24example, it doesn't matter. All you
38:25really need to know is that we can
38:27provide some attribute to filter. So now
38:30we go from all of these comments to just
38:33a select few that we care about. And
38:35this would be based off of the post ID,
38:37whatever that value might be. In the
38:39notes, I have some additional links you
38:40can do for reading on this, but I'm just
38:42going to summarize when you might want
38:44to do each one of these. So, for
38:46relatively simple data,
38:49or another way you can think about this
38:50would be few access patterns. So, you're
38:54not going to be changing the way you're
38:56accessing comments in a bunch of
38:57different ways. For example, you might
38:59just have accessing the comments by the
39:01post and by the user.
39:04In that situation, using nested data and
39:07going with this approach is pretty
39:09clean. But if the different ways you
39:11need to access the data is vast, it can
39:14be pretty complex to create endpoints
39:16for all the different possibilities.
39:18Instead, you could just group all that
39:19together into a single
39:22dude, I am hungry. Instead, you could
39:25just group everything together into a
39:26single endpoint and allow the user to
39:28filter what they're accessing by. So if
39:30you have complex asset So if you have
39:32complex ax that's freaking tongue
39:35twister. So if you have complex access
39:37patterns you know organizing this
39:38comments by a variety of different
39:40parents. Doing this across multiple
39:42different nestings can be very
39:43complicated and ugly. So you might just
39:45put it all in one and use query
39:48parameters. This choice can actually
39:49affect your code structure as well
39:51because you might have code for posts
39:56and code for users
39:58and code for comments
40:01and you basically have to decide where
40:03you're going to store the code. So there
40:05might be some jumping around or if
40:07you're working in this other pattern
40:09where you just provide in additional
40:10filtering, you can just put everything
40:12inside of a single location for comments
40:16which can really simplify the code.
40:18surface area. You don't have a bunch of
40:19places to jump around to or have to
40:21memorize some system or architecture.
40:24So, which one do you choose? All right.
40:26My personal opinion here is I prefer
40:28this structure where we access by some
40:33parent resource. So, this is what I
40:35prefer. If you have a certain scenario
40:38where you're like, hey, this is just not
40:39going to work for what I'm trying to do,
40:41then you could consider this approach.
40:44This approach would work well if you
40:46need to allow for a bunch of different
40:48filtering capabilities. Now, let's move
40:51on to how we pass data to the backend.
40:54So, we've talked about a few different
40:55options here. We've talked about query
40:57parameters.
41:01We've talked about passing data in the
41:03path. And we've also talked about
41:06passing data in the request body. So,
41:09these are the three main ways of passing
41:11data to the server.
41:13when do you use which? So, let's first
41:16take a look at these two because they
41:18have something in common. They both go
41:21in the URL.
41:24So, typically we'll use a path if we're
41:26using it to identify some data that
41:28we're referring to. So, we have the
41:30resource, but we're not just talking
41:32about a full collection of resources. We
41:34want to access a specific resource. So,
41:36very commonly, the path is going to be
41:38an ID.
41:40So ids usually passed
41:47in the path
41:50and in that situation you don't use a
41:52question mark or an and sign you just
41:54say something like slash123
41:57and this is basically a unique page
42:05or value you're referring to. So for
42:07example, an exact comment.
42:11So the path is used for identifying
42:14query parameters are usually optional
42:17and they're usually used for filtering.
42:18So if you don't provide them, it's just
42:20going to default to everything.
42:23So filtering and sorting
42:26is going to be done with a query
42:28parameter. So if we change the ID, we
42:30change the actual item we're looking at.
42:33If we change the query parameter, it's
42:36still the same path. You can think of it
42:37as the same endpoint. It's just going to
42:39change the filtering or sort.
42:44So that's really important to
42:45understand. Another thing is that with
42:49query parameters, you can stack multiple
42:52in a row. You can do that with the path
42:54as well, but there's typically going to
42:56be additional nesting. So for example,
42:58we could have comments
43:02then the comment ID. Then we could have
43:06replies
43:09and then we could have the reply ID
43:13or whatever it may be. I'm just kind of
43:15making this up as I go, but in this
43:17situation, we basically work our way up
43:19the path to get to the original
43:24entity that we're discussing. And we're
43:26providing multiple IDs so they have
43:28unique names. Changing either of these
43:30is going to change that exact comment
43:32we're talking about. Whereas for query
43:34parameters, we might have something like
43:35cars question mark,
43:40color is blue, brand is Lambo, and
43:46sort
43:47is ascending. And we can be more
43:49specific. We can say price ascending.
43:52and then the backend could still access
43:54all of these values and you use that to
43:56adjust the query
43:59to the database.
44:02You will also see the similar structure
44:03for paged data. So pageionation,
44:07so you might see page five or you might
44:10see a limit on how many you're trying to
44:12retrieve and so forth. We'll definitely
44:14get into that. So that's query
44:15parameters and the path. Both of these
44:17are provided in the URL. And generally,
44:21you do not want to do this for anything
44:23sensitive
44:26because think about it, if you have a
44:28URL, that's a URL you could share with
44:30somebody. It's something that's going to
44:31be saved in your browser history. You
44:33could favorite it or whatever it might
44:35be. It's a unique link. So, if
44:37something's private in that link, it's
44:39very easily going to be exposed and it's
44:41bad for security. So if there's anything
44:43sensitive, it always goes in the body.
44:46So for example, let's say we had a
44:48slashregister.
44:51You can do it the bad way,
44:55which would be slashregister.
45:01And then we'll provide a username
45:04and we'll provide a pass.
45:07and this is a unique URL that has my
45:10username and password that I'm trying to
45:12use for registering embedded in that
45:14URL. This is bad.
45:17Instead, we should just have register
45:19and then we'll have as part of that
45:20request a body
45:24which will then have those attributes.
45:26So, we'll have a username and a password
45:30and that will be formatted in JSON. So,
45:32it looks something like this.
45:39So, this is the proper way to do it.
45:41Anything sensitive goes in the body.
45:44This is also related to if you've ever
45:45been on a website and they have some
45:47form and you hit submit and then maybe
45:51something doesn't work quite right. So,
45:52you hit the refresh button and it'll say
45:54something like confirm form
45:56resubmission. Basically, it's making a
45:58request, a post request.
46:01So forms will use post with all of the
46:05data that you typed in as part of that
46:07body for that request. So when it's
46:09asking you if you want to resubmit that
46:11form, it's basically saying, "Hey, do
46:12you want me to send another post request
46:14to the back end? We already did it
46:16once." But yeah, translation, what does
46:18that mean for you? It means anytime we
46:20have an HTML form, it's going to use the
46:23post
46:25request type for that submission. and
46:27that means any of that data does not get
46:29added into the URL. However, if you're
46:31not doing anything sensitive and you
46:33just want to give the user the ability
46:34to sort and filter, you can make those
46:36drop downs and make the request at the
46:38back end with that in the URL. So, with
46:40this in mind, let's look at what a full
46:42request might look like. You might have
46:44post
46:47SL API/ users. So, this would be
46:49creating a new user. You could also have
46:51it be SLregister. You'll have any other
46:53headers. So you'll often see content
46:56type and this is how you basically say
46:59the notation being used for the request
47:03and this will be
47:05application slashjson.
47:08Then we'll skip down here. We'll open
47:11body
47:14and then any attributes we want to send
47:15to the back end. So here is some example
47:19data all within JSON. This is a pretty
47:22common structure you're going to see.
47:24So, for example, if you're working with
47:25API testing tools, for example, curl or
47:28some of these other tools out there to
47:29make requests to APIs and you're
47:31formatting the structure of the request,
47:33it might look something like this. So,
47:35this is an example of a header content
47:37type, really common one to specify JSON,
47:39but there are other headers you're going
47:41to become familiar with as well. And
47:43this is data that's passed with the
47:45request, but it's different than the
47:46body. You can think of headers as
47:48metadata, which is data about our data
47:51describing how to interpret the data,
47:53for example. And we'll use headers for
47:55all kinds of different things. Now, last
47:57thing I'm going to touch on briefly
47:59because we're going to dedicate a lot of
48:00the next lesson's material on this that
48:03is status codes
48:09or response codes.
48:12So just like there are standard HTTP
48:14methods, you know, get, post, put, all
48:16that stuff, there are status codes which
48:19are included with the response from the
48:21server. So we just looked at how to make
48:22a request, but the backend might give
48:24back a status code. For example, 201.
48:28This is just one example of a status
48:30code. And every single one of these
48:32codes has some implicit meaning. Now you
48:34as the API developer you can send back
48:37whatever status codes you want but
48:39generally you'll follow conventions in a
48:41similar way you do with HTTP methods. So
48:442011 this will have the text associated
48:46with it which is created
48:49and when a client sees this it can
48:52interpret that message to mean hey we
48:54likely created a new resource.
48:59So this is a common response for a post
49:02request where we're creating a new value
49:05in the database. So there are a bunch of
49:07different codes in the 100 range to the
49:09500 range. Each one meaning something
49:12unique, but there are different
49:13categories. The big ones you should
49:15concern yourself with are the 200 level
49:18which are all kind of like okay things
49:21are working.
49:24300s are redirects,
49:30400's are client errors,
49:36and then 500 are server errors.
49:40So, in the next lesson, we're going to
49:42look at more of these status codes and
49:44how you should interpret those from the
49:46client. What do you do if you get a
49:48certain status code? as well as as the
49:51API developer, how to know which status
49:53codes to use in what scenarios. So
49:56that's what we're going to get to in the
49:57next lesson. As well as once you do all
49:59of this,
50:03we now have a fairly complex
50:07interface to work with our API.
50:11We need some way to describe this to
50:14other users.
50:16So this gets into the world of API
50:18documentation and specs.
50:22Since we're following some standards,
50:24maybe people can get an idea of how our
50:26API works without us even having to say
50:29anything. So, this gets into the world
50:30of Open API and various other things.
50:33So, we're going to talk about all of
50:34that in the next lesson. So, just so you
50:36have an idea of some of the things I
50:37have for the next couple of lessons, I'm
50:39really interested in talking about those
50:41status codes, API documentation and
50:43specs, proper API architecture for
50:46scalability. We're going to look at
50:48authentication at a high level, how it
50:50interacts with APIs, things like API
50:52keys and JWTs. We will also look at
50:54pageionation and how we can transfer a
50:57lot of data to the end user in sections
51:00instead of just giving everything at
51:02once. That and so much more. So, I'm
51:04super super excited if you made it this
51:06far in the lesson. Really appreciate it.
51:07Hopefully, it was really helpful. Again,
51:09just wanted to give you a reminder to
51:10check the playlist. The playlist is
51:13where you're going to find all of the
51:15good stuff and you can just watch it
51:16sequentially. Go through this material
51:18one lesson at a time and I promise I'll
51:20help you become a much better software
51:21developer. So, super excited. I know
51:24I've said that like five times, but it's
51:26just really awesome and I'm really happy
51:27to be doing this. So, thank you so much
51:29for watching. Check out the playlist.
51:30Check out the notes for this lesson and
51:32the upcoming lessons. I'll have a link
51:33down for that below. Check out the
51:34fundamentals course and my other courses
51:36available if you're interested. And with
51:38that, I will see you in the next lesson.
51:40Thank you so much. Peace out.

About this transcript

This page contains the full transcript of API Design and Architecture - Backend Engineering Intro (1 Hour) by Caleb Curry, generated from the public captions YouTube serves with the video. The transcript has 8,377 words across 1,272 segments, with the original timestamps preserved so you can click any line to jump to that moment in the embedded player.

What you can do with it

Use the transcript to take notes, quote the speaker, build a study guide, generate a summary with ChatGPT or Claude via the YouTube Summary tool, or export it as a timed subtitle file with YouTube to SRT. You can also re-open it in the transcriber to translate the transcript into 100+ languages.

Free YouTube transcript tool

YouTube2Text is a free YouTube transcript generator — no signup, no daily limit. Paste any YouTube link and get the full transcript instantly, with timestamps, click-to-jump, translation to 100+ languages, AI prompts for ChatGPT, Claude, and Gemini, and exports to TXT, SRT, VTT, or Markdown.