Writing a Secure, RESTful Service in Zend Framework (Part 2)

Ok, so last time, in part 1, we covered the basics of a secure, Restful service with the Zend Framework. I am going to continue this series to cover what I believe are the key components required to flesh it out into a more fully mature application. However, since last time was quite an intense post from here on in, I want to make it a bit easier on both you and I.

I want to make it easier for you to have time in your busy schedule to fit in time to read an digest it, whilst still having enough technical content to make it worthwhile. For my part I want to set a schedule that I can reliably and predictably adhere to. So I plan to write a post a week until we’re done - I expect only a few further posts. With that issue out of the way, let’s continue.

In this article I’m going to cover the HTTP status codes that you should use, where and when. The reason for this is that they’re a fundamental aspect of the interaction with the service. You get this right and you will make it so much better for clients to use your service; you get it wrong and you may only have a few users and they may do a lot of work for very little gain.

Why are HTTP Status Codes Important?

Your service will typically return 2 things: a status code and a payload. If the payload is empty, a client will open it only to find nothing there, wasting processing cycles, slowing down responsiveness of their use of the service, when by receiving an appropriately informative status code, this can be avoided. With a suitable HTTP status code, say 204, a client would know not to waste time looking for content in the payload as 204 means no content.

So what ones can/should you use and when (there are more, but I want to focus on a few key ones):

200 OK

Simply put, the operation, whatever it was, was a success.

201 Created

Use this one after creating a new resource to indicate that it was successful

204 No Content

Use this after, for example, a search operation to indicate that the operation was successful, but that nothing was found.

205 Reset Content

This indicates that the operation was successful, and a web form could be reset to a default. It’s more specific when working with forms than the HTTP 200.

300 Multiple Choices

This indicates that given a request, there are multiple options that will, potentially, satisfy it. It provides the opportunity to get input from the user as to which option best suits their needs.

301 Moved Permanently

Otherwise known as an SEO-301 Redirect, this is great for keeping “link juice” on web sites and for simply saying that the content is still available, but now known at a new location.

304 Not Modified

Indicates that there’s been no change in the underlying resource. This helps with caching. If you provide a service returning a 304, a client can refer to a cached copy of the content, if available, resulting in less processing for them and you.

400 Bad Request

Indicates to the client that the request that they made was unable to be handled due to something in their request. This could be include such things as an incorrect or questionable query argument.

401 Unauthorized

One of the most well known of status codes. This just says that the client has insufficient authority to make the request.

403 Forbidden

This takes a 401 a step further in that no access is available to this resource, irrespective of the users credentials.

404 Not Found

Another of the big daddy of status codes. Clearly put, the requested resource is not available.

408 Request Timeout

Simply put, the client was too slow in responding to the server, such that a timeout occurred. There were no issues involving authentication credentials.

409 Conflict

This would occur where a service was updating a resource and there was some contention in carrying out the process, such as updating a user account. It would be a good indicator to the user that some of the data supplied needed adjusting.

410 Gone

This says that a resource that was previously available now isn’t. Unlike a 301, there’s no information to allow for a redirect to a new location.

412 Precondition Failed

This is great to use, as the name would indicate, when a user was performing a CRUD operation, but some of the information didn’t meet the criteria for completing the operation.

415 Unsupported Media Type

This is great for writing, say, a media server and enforcing only certain types of content types to be uploaded. It indicates that one being uploaded was, as the name says, unsupported.

422 Unprocessable Entity

This indicates that the information supplied by the user was correct, but something about processing it resulted in the operation failing. It’s a little bit ambiguous for the user to know what that was, but it’s better than nothing.

500 Internal Server Error

This is one of the other grand-daddy of errors. Something, or some nature, went wrong on the server when attempting to carry out the request.

501 Not Implemented

Simply put, if you want to show this to the user, it just says that the request that the user’s making is not yet available.

503 Service Unavailable

Great for having a maintenance mode on your server. This just says that currently the service is unavailable and may be up later.

507 Insufficient Storage

This, as the name implies, allows the user to know that the server is out of space.

As you can see from that list, there is quite a range of status codes.to suit the majority of circumstances that a typical application may encounter. So now that you have a sound knowledge of which codes to use and when, you can now start building more effective and less resource-hungry applications that are more responsive to user needs.

Till next time when we get further in to authentication and access control.

P.S. Many thanks to http://restpatterns.org/HTTP_Status_Codes for constantly being a solid source of information about REST.