YT YouTube2Text

YouTube2Text → Transcripts → API Status Codes and OpenAPI Documentation - Backend Engineering

API Status Codes and OpenAPI Documentation - Backend Engineering — Transcript

by Caleb Curry · 4,315 words · 653 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. In this lesson, we're going to
0:02talk about the HTTP status codes that
0:05you need to know when you're building an
0:07API. Now, before we get started, I will
0:09tell you that you can get the playlist
0:11link down below so you can watch all of
0:13my back-end engineering videos. That'll
0:15get you started with an intro to APIs
0:17lesson. And the second thing you need to
0:19know is that I have the notes for this
0:20lesson and all the other lessons. You
0:22can get that as well in the link below.
0:24So that'd be great if you want to follow
0:26along with some code examples as well as
0:28a ton of additional resources and links.
0:30So would really recommend that to get
0:32you the most success possible here. So
0:34we've already talked about APIs. It's
0:36basically a way to make a request to a
0:39backend and then the backend will give
0:41back a response
0:44and this will include a code
0:48such as 200 and these will also have
0:51some message associated with it such as
0:54okay. So these codes they have some
0:57implied meaning but you as the backend
1:00developer usually decide what code to
1:03send to the client. So let's say the
1:05client makes a request for some data
1:11that hits the server. The server then
1:13checks the database
1:16and the database does not find the data.
1:19Whatever they're looking for is not
1:21there. So the server can then respond to
1:23the client
1:28with a 404
1:30not found.
1:33But you can control that. You can return
1:35whatever you want. There are just
1:37conventions and approaches that if you
1:39follow these approaches, you will create
1:41an API that people already know how to
1:43use. Additionally, you can follow a spec
1:47or a specification and this will allow
1:50for very easy consumption of your API.
1:53So the most common example of this would
1:55be an open API spec.
1:59And basically, if you want to use one of
2:01these specs, you just describe the
2:04behavior of your API, what data is
2:06expected, what kind of responses might
2:08be given back, and you put all of that
2:11into a spec file, which can then be read
2:13by other software. So, we'll definitely
2:15get into this idea in more detail, but
2:17this is a concept video, so we're not
2:20going to build an open API compatible
2:23API in this lesson, but we'll probably
2:25do that in upcoming lessons. So, again,
2:26check out the playlist link down below.
2:28So, if you're watching this video, you
2:29may already understand the basics of
2:31APIs, but you want to know the proper
2:33way to build an API. Maybe you can build
2:35an API, but you want to know the proper
2:38conventions, the proper structures, the
2:40way you return data, what status codes
2:42to use. That's what we're going to cover
2:43in this lesson. So, before we get into
2:45the status codes, we're going to talk
2:47about the body structure. So, with a
2:50request and a response, you can include
2:51a body. And I want to talk about the
2:53conventions for returning data from the
2:55server. We can do one of three things.
2:59We can return an array of data.
3:03We can return an object
3:05or we can return the data as an
3:08attribute
3:12of another object. So we would be
3:14returning data as a nested object.
3:20So these are three different approaches
3:22and not all of these are correct. So,
3:25while it's technically possible to just
3:27return an array directly from an API,
3:30it's not considered best practice. So,
3:32for example, let's say we had users on
3:35our app and they were able to configure
3:37their profile settings and one of the
3:40things on here was notification
3:42settings.
3:45And let's say they could get
3:47notifications for marketing information.
3:49They could get notifications from any
3:51replies to their comments. and they
3:53could get notifications for security
3:55issues with their account. So these
3:58might be in an array
4:00where we have marketing
4:04replies and security.
4:11So if we wanted to get the person's
4:13notification settings or the same idea
4:15if we wanted to update the user's
4:17notification settings, the method and
4:20the path would look something like this.
4:22We could use a get for retrieving this
4:24information
4:26or we could use a patch for updating
4:29this information.
4:32Then we would have slash users
4:35slash the ID of the user slash
4:39notifications
4:41or you could have a more general slash
4:43settings. But let's just say we're
4:45working with notifications directly and
4:47we want to get this data for a
4:49particular user. So let's say user 1 2
4:513. What does the response body look
4:53like? Well, it's considered bad practice
4:55to just return an array. So, the proper
4:57way to do this would actually be to
4:59encapsulate that array in an attribute
5:00of an object. So, that might look like
5:03this. We have a curly brace and then an
5:05attribute
5:07notifications
5:11and then the value of that attribute is
5:13the array and then we can close the
5:15curly brace. Same idea when we send data
5:18to the server. or if we were to use a
5:20patch, we would nest that array in some
5:24attribute. I think that's considered
5:26best practice. So, you always want to be
5:28working with the first level being an
5:30object.
5:33Inside of that object, you can do pretty
5:35much whatever you want. Let's go through
5:36another example. Let's say you wanted to
5:38get all of the users.
5:42Well, users is going to naturally give
5:44us an array. And this would be an array
5:47of objects. So within the square
5:50brackets you would have multiple
5:52objects. So it would look something like
5:54this where each one of these is a user.
5:57However, same idea here. I don't think
5:59it's ideal to return an array back to
6:02the client. So instead we would nest
6:04this in a bigger object. So it looks
6:07something like this.
6:10users
6:13square bracket and then that data.
6:20So this is the proper response. Now a
6:22scenario where this is a little less
6:24clear is if we're working with an
6:25endpoint that doesn't directly give us
6:27an array. What if we want to say
6:33get
6:36get users and pass in a specific user
6:39say ID 3 2 1. Well, this is going to get
6:42us a single user. So, the response type
6:44is an object. We can give a a quick
6:47example here such as name
6:51being Caleb.
6:55So here's where you have basically one
6:57of two options. We can return an object
7:00or we can return data as a nested
7:02object. So you could basically just
7:04return this
7:08and that would work fine.
7:11That's pretty common, but it's probably
7:13not as ideal as still returning the
7:16object as a nested attribute in a larger
7:20object. Just like we did with the array,
7:22it's just now a single user instead of
7:24multiple users. So we would have user
7:27and the value for this would then be
7:30that object.
7:32So it looks something like this.
7:36So that closes this inner object and
7:38then this outer curly brace closes the
7:41outer object. So you can see that this
7:43structure and this structure is
7:45consistent. We basically have an
7:47attribute describing what the data is
7:49and then we have the data where that
7:51data is either an array or an object.
7:53This is pretty much what I would always
7:54do. So just nest it in some attribute
7:57and you can describe what the data is
7:59such as saying users or user. So the
8:01conclusion from this is even if you're
8:02working with an endpoint that gives us
8:04just a single object, we still nest it
8:06inside of a larger object. And there's
8:09one other major benefit to this other
8:11than just being consistent and that is
8:13it gives us the ability to add in
8:15additional information into this outer
8:18object without affecting the inner
8:22object. So you can see we have this
8:23inner object here and I guess we'll
8:26include the attribute name.
8:30But for this outer object, we can put in
8:33extra information to describe the
8:35request, pass in status information,
8:38continuation tokens or whatever it may
8:40be. It basically gives us room to
8:42provide additional information to the
8:44client without impacting the actual data
8:47they care about. So here's what that may
8:48look like. We can have a large outer
8:51object. The thing we're giving back to
8:53the client is a user.
8:56This contains an object with some
8:58attributes such as name
9:02that has a value Caleb.
9:05And then we'll close that object. You
9:06can additionally put in different
9:08attributes here and close the object.
9:10We're just going to have one attribute
9:11now for simplicity. But this outer
9:13object, we're going to keep that open.
9:14And we're going to then close it down
9:15here, which gives us room to add in
9:17additional attributes.
9:19So, we could have a meta attribute for
9:22any kind of metadata about the request.
9:25I'll just draw that as an empty object.
9:27We could have an API version
9:30and that could just be a number.
9:32Sometimes the response is embedded in
9:35the body even though it's a little bit
9:36redundant with the HTTP status code in
9:39the actual response, but that is
9:42possible to see. So we'll say response
9:45200 or if we're working with a list of
9:49users
9:51maybe we have to do pageionation and
9:54that information could be included here
9:55as well.
10:00So we may have a continuation token
10:04and the client can then access this
10:07attribute to know how to make another
10:10request.
10:14So, I haven't really talked about paging
10:15yet. That's not the important part here.
10:17The important part is that we can add in
10:20a bunch of additional information if we
10:22need because of the way we structured
10:23the response. So, this is the structure
10:26I'm going to follow. A very easy way to
10:28structure this in the code would be to
10:30create some variables such as data. And
10:31here you would make a database call. I'm
10:33just making this up, but it might be
10:35something like users.get.
10:39And then when you return a response,
10:43you can just take this variable,
10:45regardless of what it is, whether it's
10:46an object or an array, and provide that
10:49inside a dictionary
10:51like so.
10:55So you'll see this structure quite a bit
10:57where in our code we're working with an
10:58array or a single object, but then when
11:00we actually provide the response, we
11:02just embed it in a dictionary with
11:04another attribute. But again, we could
11:06then add anything inside of here besides
11:09the users attribute. We could add any of
11:12these things. So hopefully that's
11:14helpful in understanding the proper
11:15structure for the response. Cool. So we
11:17got that out of the way. Now we can take
11:19a closer look at status codes. So off
11:22the top of my head, the ones you should
11:23know immediately are 200, 2011,
11:27204,
11:29301, and 302,
11:32400, 403,
11:36404, and 500. So if you know all of
11:39these, you'll be pretty good. And each
11:41one of these will also have a small
11:42description attached to it. So for
11:44example, 404
11:47not found.
11:49I'm not going to necessarily write that
11:50out every single time or say it out loud
11:52every single time. So, just know that
11:54each one of these will have some message
11:56with it. So, let's go through each one
11:57of these. 200 is okay. That means
12:00everything worked as expected. You'll
12:02likely get some data back. 2011 created
12:05usually means you're creating some new
12:07resource and it was successful. 204, no
12:10content. This basically means it was a
12:12success, but the server has nothing to
12:14give back to you. 301 and 302, these are
12:16two types of redirects. a permanent
12:18redirect and a temporary redirect. So
12:20this is 301 move permanently and then
12:22302 found 400 bad request. This implies
12:26an issue with what you're sending from
12:28the client to the server. So maybe
12:30that's an issue with the way you
12:32structured the body and you need to fix
12:34that. 404 not found means the path
12:36you're giving doesn't exist. And then
12:38lastly, 500 internal server error. This
12:41means something went wrong on the server
12:43side. So this is a client error.
12:45Something's wrong with the request. this
12:47is a server error. Maybe there was an
12:48error with the database. So your job as
12:51the person building the API is to use
12:53the proper status codes to describe
12:55what's happening. To get to the solution
12:57to this rather quickly, there's
12:59basically five different request
13:01categories and the different responses
13:03for them. So we have
13:07a get for many elements,
13:11a get for a single element, a post,
13:17a put or patch,
13:20and a delete. Now, there are more method
13:23types. These are the main ones you
13:24should be familiar with starting out.
13:26And if you got all this down, the
13:27concepts are there, and you can pick up
13:28all the others quite easily. So when
13:30you're getting many that would be
13:31something like slash users and things
13:33work you will either get some data or
13:36you will get an empty array. So this is
13:38going to give 200 and return an array
13:42and keeping in mind that'll be an
13:43attribute inside of the response object.
13:46But it'll either be an empty array or an
13:49array with data. You're not just going
13:50to give back nothing. Now if you're
13:52getting a single resource that would be
13:54something like users
13:57ID 1 2 3. This is going to give an
14:00object. So you'll get 200 and an object.
14:04However, this could also give a 404 if
14:07that object is not found. So that is an
14:10important thing to understand here. If
14:12you're getting many and nothing is
14:14retrieved, for example, you want to get
14:17all of the comments on a video, but that
14:19video has zero comments, you're going to
14:21get an empty array. However, if you're
14:23getting a single element and the element
14:25does not exist, you're going to get a
14:27404. you're not going to return an empty
14:29object. So, we could potentially get
14:31back a 404 if we're getting a single
14:33element. It'd be like if you put an ID
14:34here that wasn't in the database. Now,
14:36for post, you will usually see 200 or
14:40201.
14:42So, usually 201 is used for creating new
14:44data. And then often this will return
14:48the ID of the newly created thing or the
14:51new object entirely.
14:53This can also give back a 400 if you
14:56give bad data to the request. So if the
14:59data you're trying to create is invalid,
15:02then you can get a 400. Or if that
15:04insert is not working properly, you
15:06might get a 500 for the server error.
15:09Now put or patch, you will often get a
15:11200 or a 204,
15:14which basically says it works, but the
15:16server doesn't give back any data. If
15:18it's a 200, you will often get the
15:20updated object back.
15:23possible issues. We can now get a 404.
15:26If the resource we're trying to update
15:28doesn't exist. So, for example, if we
15:30were trying to update users
15:331223, but 123 didn't exist, we could get
15:35a 404, but we can also get a 400 for bad
15:39data or a 500 for an issue on the
15:41server. And then lastly, delete. I'll
15:43usually do a 204, but you may also see a
15:46200 with the response being the number
15:48of affected rows or some other
15:51variations. This isn't necessarily the
15:53only way to do it. This here is not the
15:55spec. The spec is adhering to a proper
15:58HTTP protocol, but you can choose what
16:01can possibly happen, and this is what's
16:03going to show up in your documentation.
16:05So, I'm just showing some common things
16:06you'll likely see. So, if you're like,
16:08"Oh, I don't know what status code to
16:10use for a post or a delete," here's your
16:12answer. Now, a delete could also give a
16:15404 if we're trying to delete something
16:17that doesn't exist or a 500. It's
16:20probably not going to give a 400 because
16:22that would imply bad data from the user,
16:24but you're not really providing data to
16:26the back end for a delete beyond just
16:27the ID of the thing you want to delete.
16:30So, usually you're going to get a 404 or
16:32a 500. And then we're not really
16:34worrying about 301's and 302s, but those
16:37are good to know about. And then 403
16:39here, we didn't talk about this because
16:42we're not really concerned about
16:44authorization or authentication here. So
16:46we're going to talk about that, but you
16:47can think of this separately from our
16:49core functionality. So the client can
16:51use these status codes to adjust its
16:53behavior. So for example, if we make a
16:56request to post slash comments,
17:01what were the potential returns for
17:03this?
17:04If it was a success, we'll get a 200 or
17:07a 2011. If there's something wrong with
17:09our data, we could get a 400.
17:12If there's something wrong with the
17:13server with the insert or something
17:16along those lines, we could get a 500.
17:20Additionally, to post a comment, you
17:22might need to be logged in probably. So,
17:24can have another option here with a 401.
17:28So, we basically have four possible
17:30paths we have to consider on the client.
17:33If it's a 200, we could add the comment
17:35to the feed so it visually looks like
17:38our comment was posted. If it's a 400,
17:40we might say, "Yo, try again."
17:44And maybe we could figure out a little
17:46bit more detail why it's a 400. So if
17:49you have some backend validation
17:50library, it will usually give some more
17:53specific error that you can send back in
17:56the response. So it might say something
17:58like, "Oh, the body is required or the
18:01message is too long or whatever it might
18:02be." So you can show that error.
18:08So, show error and then prompt the user
18:11to try again. You don't just try again
18:14without any changes because that client
18:16error isn't going to have been fixed
18:18automatically.
18:20That might be different for a server
18:21error. Maybe something went wrong and we
18:22just want to retry. But basically, with
18:24a server error, we would just say a
18:27general error message.
18:30We usually don't want to give too much
18:31information about issues from the
18:33server. So, we keep it pretty general to
18:35the client. If it's a 401, we can
18:38redirect
18:40to the login page. So, you can see how
18:42these status codes can be very handy
18:44because it allows us to build a client
18:46that can respond smartly to whatever
18:48happens from the server. Next up, I want
18:50to talk about a concept called
18:51middleware. And this can be very handy
18:53when we are building out responses. And
18:55often middleware steps can return
18:58different status codes. So far, we have
19:00been taking requests and coming up with
19:04different responses. But this processing
19:07is just one piece in a much larger
19:10request cycle. So I'm just going to draw
19:12this as a box. But what it might really
19:14look like is you receive a request from
19:17the client on the server
19:20and then it goes through some steps. So
19:23for example, it might go through an off
19:26middleware which is a really common
19:28structure.
19:30And then before we give the response
19:33back to the end user, we might have some
19:36formatting or some internationalization.
19:40So these things effect on the after
19:44processing of the request and then we
19:46can send it to the client.
19:49So basically things can happen before
19:52the request and after the request that
19:55can modify the request or modify the
19:57response. So earlier when we mentioned
19:59the most common methods and the common
20:01status codes I was kind of like hey you
20:03can worry about off separately that's
20:06because you could have an off middleware
20:08and this verifies the user so it checks
20:12for authentication authorization
20:15so very similar ideas slightly different
20:18authentication is basically saying hey I
20:20am who I say I am I can prove that to
20:22you here's my username and password
20:25whereas authorization deals with do I
20:28have access to what I'm trying to
20:29access. I might be able to log in, but
20:32do I have the permissions to do whatever
20:34I'm trying to do? So, two slightly
20:37different ideas. And it's even super
20:39confusing because the 401 status code
20:42generally means the person needs to log
20:44in. They're unauthenticated,
20:47but the message with it is unauthorized.
20:54So, don't let that trick you. And then
20:55there's a 403 forbidden
21:02which is really the unauthorized. So
21:05this is
21:07unauthenticated.
21:11Can't even fit that in there. And then
21:12this is unauthorized.
21:16So you can almost think of these as
21:17backwards.
21:19So we'll get a 401 when the user needs
21:21to log in and then a 403 if they're
21:23trying to do something that they're not
21:24supposed to be doing. So all of these
21:26capabilities can be encapsulated in a
21:29separate function as part of the
21:31middleware pipeline.
21:34So each one of these steps would be a
21:35step in that pipeline. And the request
21:37goes through this linearly, one at a
21:39time, with each step potentially
21:41modifying or adding to or changing the
21:45request that passes through this
21:47pipeline until it ultimately gets back
21:48to the client.
21:50So this doesn't change the end output
21:53for the user. It just changes the way we
21:54structure our application and think
21:56about requests. So this is more a code
21:59organization and scalability of our code
22:02idea. The end user doesn't see or know
22:04anything about this. We may also have
22:07things like validation
22:12and this could potentially return 400s.
22:16So then we wouldn't even have to worry
22:17about 400s in the request in the section
22:20where we're processing the request
22:21because if they make it through the
22:23validation and they didn't get a 400,
22:26then we know the content
22:30is valid and then we can process it.
22:34So this allows our core processing logic
22:37to be very thin
22:40and single focused basically. So it's a
22:42very nice way to organize and structure
22:44our code and then we don't have to
22:46repeat logic in every single function.
22:49Very very important. Last thing is API
22:52documentation
22:53and specs.
22:56So it's often the case whatever library
22:58or language you're using
23:03will have some way to work with
23:08or document
23:14your API and this might be some specific
23:18internal tool for that library or it
23:20might use external things like creating
23:23an open API spec file. So your library
23:26might be able to generate a YML orJSON
23:33file
23:35and this can then be read by other tools
23:39to generate docs
23:43and interfaces to work with the API.
23:47This is huge. Anytime you can generate
23:49stuff, you should probably do it. So an
23:51example of an other tool here would be
23:53Swagger.
23:56And this is closely associated with open
23:58API, but it's not the same thing. Think
24:00of Swagger as the tool. Open API is the
24:04actual spec, but Swagger can read Open
24:07API documents and give us a very easy to
24:10use UI to interact with that API. So
24:13then if you're working in a team or you
24:15need to share this API with other
24:16people, you don't have to tell them what
24:18every single possible thing is. they can
24:20just look at the UI and see the possible
24:22inputs and potential errors or output
24:24concerns they need to consider. So this
24:26makes building the actual interaction
24:29between the back end
24:32and the front end
24:35a thousand times easier.
24:38So check with whatever library you're
24:40working with if they have a way to
24:41generate the open API spec or there's
24:44likely another library for the language
24:46that you can download to do that. If
24:47not, you can create these files yourself
24:49manually. It's not like impossible. So,
24:51you can do that as well if you're
24:53working with a perhaps newer language
24:55that doesn't have as many good libraries
24:57out there. There are also other options
24:59for documentation. For example, there's
25:01Postman.
25:04And this is generally considered a tool
25:06to interact with an API, to test it, to
25:08build an API. You can think of it as an
25:10alternative to a web browser, but with
25:12stronger support for the different
25:13methods and the different variations
25:15you'll need for testing APIs. But you
25:17have the ability in Postman to create
25:19collections
25:21and collections can act as a
25:24documentation for your API basically
25:27showing what endpoints, what they
25:29expect, and so forth. And Postman has
25:31ways to generate docs
25:37from these collections. So, in the
25:39notes, I'll leave additional information
25:40if this is something you're interested
25:42in. Last couple of things I want to
25:43mention just as a bonus here is you can
25:46also utilize AI, which should be able to
25:50document APIs on the fly.
25:54So, that's another alternative is to
25:56actually document when you need the API
25:59using AI. Or another thing I want to
26:01mention is you can go through the effort
26:02to build a docs website such as
26:05docysaurus or some other markdown
26:07renderer.
26:10This is pretty important or more common
26:12for public APIs.
26:16So that's something you might want to
26:17look into as well. That's all I have in
26:18this lesson. Hopefully it was a good
26:20introduction to the different codes you
26:21might run into. There are a ton, but the
26:24ones we covered are the most important
26:26to get started. And as we build out APIs
26:29here soon, we will see these again.
26:30Thank you so much for watching and stay
26:32tuned for the upcoming lessons. Be sure
26:34to check out the playlist link. That's
26:35where I'll put everything. And I'll see
26:37you in the next one. Peace out.

About this transcript

This page contains the full transcript of API Status Codes and OpenAPI Documentation - Backend Engineering by Caleb Curry, generated from the public captions YouTube serves with the video. The transcript has 4,315 words across 653 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.