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