LornaJane

This the last entry in a mini series on points to consider when designing and building web services. So far there have been posts on error feedback for web services, auth mechanisms for web services, saving state in web services and using version parameters with web services.

Unlike the other posts in this series, this one is quite specific to one type of service - REST - since it deals with status codes, specifically HTTP ones. The ideas are transferrable however and other types of service can return statuses in a similar way.

There's a few key things to think about when returning status codes. In earlier posts in this series these was discussion of using existing application framework to serve pages and changing the output mechanism accordingly. Usually a web page will return a status 200 for OK or also 302 for found, so this is fine when things are working normally. But when things aren't going quite so well, its useful to give alternative feedback that can be easily picked up by a client application.

When things go wrong there are a couple of different schools of thought of how the service should respond. One is that if, for example, the user supplies data which fails validation, the service could provide the OK response and a message to the user to let them know what needs validating - exactly as we'd return information messages to a user filling in a form. To be considered restful however, the service should more correctly return one of the "400" status codes, which means that the client made an error. Interesting and useful codes* in this series are:

• 401 Unauthorized


• 403 Forbidden


• 404 Not Found


• 405 Method Not Allowed


• 406 Not Acceptable


• 408 Request Timeout


• 417 Expectation Failed


• 418 I'm a teapot

* I didn't say they were both useful and interesting

Using descriptive status codes allows the client to get the headline of the problem without having to parse a whole request to find out whether it is good or not. HTTP already has this feature built-in, and so we make use of it (HTTP is pretty cool really, makes a great protocol for services!).

Where an error occurs on the server side - it is usual to return a 500 error or another in the 500 series. This lets the client know there is a problem outside of their control; it is useful to include information about whether the client should retry and when. Having a defined protocol for retries helps avoid the situation where a system comes back up only to fall over again with all the traffic from people retrying every minute (or other interval) - this is a real concern for systems that are under heavy load.

Status codes are like a headline to the calling entity about what happened, and are a valuable tool in the web service toolkit. For bonus points, leave me a comment and tell me which is your favourite status code :)