RESTful and HTTP APIs in Pyramid Transcripts
Chapter: What is REST?
Lecture: HTTP status codes
0:01 We've seen that http verbs are super important for the client
0:04 to communicate with the server.
0:06 I would like you to do this type of operation get me the data, get;
0:09 create an item here, put, and so on.
0:13 The opposite of that, the server communicating effectively back to the client
0:18 that has to do with http status codes.
0:20 Now we all know status codes from playing with the web right,
0:23 200 means everything's good, 404 means gone,
0:27 500 means server broke, whoops, things like that.
0:30 But there's actually a much wider spectrum of options
0:33 and using those wisely means your service is really a proper restful service,
0:40 and not just something hijacking the http transport layer to move stuff around.
0:46 So let's look at status codes and pick out a few of the important ones.
0:50 So I'm here in this site called httpstatuses.com,
0:53 created by a company called Runscope they do like API monitoring tools and stuff,
0:57 that's not important, what's cool is here we have a bunch of status codes
1:03 all broken down for us, and we can click on them and see what that means,
1:06 like everything is going to be ok, 200 ok right,
1:10 you can see well this means the request has succeeded
1:13 and you can see the various situations where it might make sense
1:17 for a get or a post, or a put, something like that.
1:21 So 200 ok, this is great for get and things like that.
1:25 Now if we're going to do an http post, you don't want to say well that's just okay,
1:29 remember you need to say we've created an item for you
1:32 that was the intent anyway, and maybe we need to tell you where it is;
1:35 so let's look at 201 created.
1:37 This means the request has been fulfilled
1:40 and has resulted in one or more new resources being created,
1:45 and in fact, the request is probably identified by a location header field
1:49 if not, maybe there's like some kind of redirect or something like that.
1:52 And even have like the Python status codes
1:56 if you want to try to get the enumeration for them, but that's not so important.
2:00 So the two important ones, for 200 are 200 ok and 201.
2:05 We also have 202 and 204, these are both interesting
2:09 so accepted means it's kind of like what you might give for a post operation
2:14 like hey, you sent me something and I'm working on it,
2:17 but what if you're using like queuing,
2:19 and I'm going to put this in a background queue,
2:21 eventually we'll pull it off the queue and process it
2:23 but I can't be sure it worked ok now;
2:25 so this is what you would send to them instead to say
2:28 I think it's all going to be ok but I can't be sure because we haven't processed it yet.
2:31 Also, no content, this is like the servers fulfilled the request
2:36 and I have nothing more to tell you,
2:38 this would be a great response to an http delete
2:41 or maybe even like http put, something like that, right,
2:43 you've asked me to delete it, that was fine, everything worked, it's gone.
2:48 So those are the two hundreds, now if we go into three hundreds,
2:52 these are the redirection ones, most important one is probably either found,
2:56 a soft redirect at 302, or a permanently moved over at 301.
3:03 So this is like I changed my domain, it's over here,
3:06 and it's always going to be over here now, it's never coming back.
3:09 Then we have client errors, four hundreds, and down here 500, server error.
3:14 Hopefully you don't see any five hundreds but it's going to happen, isn't it.
3:18 Okay so 400, you can say I have request this is really important for services
3:22 it might mean you've given me some kind of data,
3:27 you said it was json but it's malformed, I can't process it.
3:30 Or it could even be, you've given me a piece of json
3:34 but not all the values I require are there,
3:37 so you could somehow say no, this is a bad request,
3:43 unauthorized permission stuff right, payment required, we all want to get paid, right
3:47 but 403, you don't have permission, even if you're authenticated,
3:51 and 404 not found, this makes a lot of sense if somebody does a get request
3:55 against like /api/book/72, and there's no book with id 72,
4:00 you want to return not found, okay, there's no way we can give you this it's not here.
4:05 Now, there is one other one, that's really worth talking about here,
4:10 I guess maybe a couple, we have payload too large for certain things
4:14 you might be uploaded to large,
4:17 gone- just gone, timed out, these are all interesting,
4:20 but I want to direct your attention to a very important status code
4:23 what we're here anyway, number 418, I'm a teapot,
4:28 and the official server response is any attempt to brew coffee with a teapot
4:31 should result in an error code 418, I'm a teapot, I can't brew coffee,
4:35 the resulting body may be short and stout,
4:38 so this is actually a joke played with the html http team committee,
4:43 and some kind of joke on April Fools' or something
4:46 and they decided to leave it in, it's kind of funny.
4:49 If you ever want to make somebody laugh
4:51 and you're doing some testing, just return 418.
4:53 And of course, we have the server 500 errors,
4:56 you really shouldn't be sending these back, right,
4:59 maybe not implemented internal server error, this is really an unhandled exception
5:05 you should probably catch the error and somehow
5:07 return it in some other form, right, if the reason there'll be 500 error is
5:14 because maybe you tried to access an object
5:16 but it didn't come back for the database, it was none,
5:18 so you got some kind of exception there, you probably want to return a 404
5:21 instead of letting that crash the server and return 500.
5:25 So that's http status codes, if you are unsure that's a pretty good site
5:29 just go to httpstatuses.com and pull up the detail page for any one of these
5:33 and try to decide is this the best thing to send back,
5:37 does this make the most sense for my service.