RESTful and HTTP APIs in Pyramid Transcripts
Chapter: What is REST?
Lecture: HTTP status codes
Login or
purchase this course
to watch this video and the rest of the course contents.
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.