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.
Matthew Setter is a PHP & Zend Framework specialist. If you're in need of a custom software application, need to migrate an existing legacy application, or want to know your current application's GPA - get in touch.