RESTful APIs Part 3

Continuing from the last post where we talked about making a request, or sending information to the server, we will cover responses, or receiving data from the server.

As with REST verbs being built into HTTP as request methods, HTTP also has some built in header support for responses. These response headers are called status codes. They are a set of predefined codes that we can look at to see if our request was successful or if it had an error. But the codes don't just say if the request failed or not but also says where and what was done about a success or failure. There are a lot of different error codes but we only really need to know their grouping and a few common responses.

Status codes are three digit numbers which start with 1 through 5.

100 Status Codes

You can basically ignore 100 level status codes since they are used for providing information on the status of the communication. They are used for stuff like CORS (cross-origin HTTP request) and stuff like changing protocols. At some point I will talk about CORS. Even for CORS you wont need to worry about 100 level status codes. The exception to this is if you are writing foundation library code for communication, in which case you will want to have a much deeper understanding of HTTP then I am going to cover.

200 Status Codes

The 200 level status codes are success responses. So seeing a response starting with a 2 is a good sign. Some of the most commonly used of these are:

200

200 is a simple OK. This basically is the same as just saying success with no additional information about it. Normally if something was successful all you need is to know that it worked and then look at the attached response.

In RESTful APIs most responses will include a 200 status code and the body will contain a JSON representation of the data you requested.

So in a GET request for Fuji apples:

/fruit/fuji-apple

From the last blog you could expect a 200 status code and a body something like:

{
    "id": "fuji-apple",
    "name": "Fuji Apple",
    "color": "red",
    "season": "October"
}

201

201 means that a record was created. You would get this status code when you do a POST. Also the 201 may or may not have the newly created record included in the body.

So in our POST request to create the Fuji apples in the orchard we can expect a 201 response and the documentation should tell us if we will get the newly created record returned. The main reason you may want to get the full record returned is so that you have the newly created ID and any other generated fields, maybe a created date field or the user who created the record.

204

204 indicates that there is no content. This is used when there is no body that needs to be returned such as when you do a DELETE.

So when we sent a DELETE request to:

/fruit/fuji-apple

We wouldn't have expected any content or data returned since we don't need the Fuji apples record since it was removed.

300

The 300 level status codes mean that a redirection occurred. In other words you send a request and the server decided that you didn't actually want what you asked for but instead wanted something else.

301

301 is a permanent redirect. These are used when you change your domain or the structure of the pages on your site but you want to accommodate those who still have the old URLs bookmarked and to preserve your SEO since the search engines know that the old site was permanently moved.

304

304 means not modified and so the server isn't returning anything. This may seem a bit strange but the idea is that your browser has a file cached that may be what the user is needing but it asks for the file and says it has x version of the file and then if the server sees that it is the correct version it tells the browser to go ahead and use its cashed version.

400

The 400 level status codes mean that there was an error and it was the clients fault. So the request had something wrong with it or it was for something that doesn't exist or the client doesn't have access to.

This is the level with the largest collection of possible responses. Which makes since because when you are a client connecting to the server you can't debug the server and so the more information that you can get from the server about what was wrong with your request the more likely you can fix the problem.

While there are lots of requests we will mostly just cover the common ones.

400

400 means you had a bad request. Alone this isn't very helpful since it just means your request has a problem with it, normally bad syntax, missing or extra parameters, or poor formatting. So this should always include more information about what went wrong with the request so that it can be fixed.

401

401 means you are not authorized. So if only someone logged in as an orchard manager is allowed to add or modify fruits then anyone else who tries to do a POST or a PUT to the /fruits endpoint should get a 401.

403

403 means you are forbidden to make the request. This is different from a 401 in that it means that no authorization will give you access so don't try the request again.

I have most often seen this response when I did something wrong with an Apache or other web server setup, normally when it doesn't have access privileges to the files it is serving. This can be confusing since this particular situation is actually a server error.

There may be other situations where this occurs but I haven't noticed any.

404

404 is actually the most common client error you will get while browsing the web, it means that your resource was not found. These are the responses that often get the cute jokes about something going wrong which are shown to users browsing. It should be pretty obvious that if you ask for something that doesn't exist you messed up and that is what this means.

A common scenario is that you bookmarked or otherwise stored a URL and then the resource went away. So lets say that we were excited about the Fuji apples and so you have an app check to see if it is ripe yet. Then when the Fuji apples are removed because the tree dies you will start getting 404 errors since it is no longer available.

500

The 500 level status codes indicate that there was an error but it was a problem with the server and so there is nothing you can do other then contact the server's maintainer and have them look into it, or wait.

500

500 is basically the only one you will generally see and it is pretty generic meaning internal server error. If you get this you know something is wrong so you may try again, let the user know there was an error, or log the error. There isn't anything you can do about these errors on the client side so you have to figure out how you will respond since you will get these occasionally.

Next Time

This wraps up tying REST and HTTP together. Next up we will be going into more detail on what REST actually means.

comments powered by Disqus