Recently, I have been looking at various APIs again. Social media sites like Digg, Twitter, Facebook, etc, add new features to their API all the time. Working with these APIs is fairly easy, especially when you are using a library to do much of the work. Because of this, I have a feeling that we, meaning developers, have started to cut corners in our applications. I admit to doing the same thing and I am working towards fixing those problems.

One of the reasons for my concern is that Google decided to redirect my Feedburner feed and I was not notified that this was happening. What happened was, Feedburner changed my feed location from the previous future of http://feedproxy.google.com/RegularGeek back to the deprecated but redirected and now permanent again http://feeds.feedburner.com/RegularGeek. Generally speaking, this is fine because one feed location is redirecting to the other with typical a HTTP 301 header. However, depending on the library you are using, you may not be handling a redirect in your code. What this means is that some applications may fail to appropriately update based on your feed content. This happened with a few applications that process this blog’s RSS feed.

What does this have to do with APIs of social media sites? Well, many of the APIs use HTTP response codes for error reporting and basic status reporting. For example, Twitter has an entire wiki page devoted to HTTP Response Codes. The important thing is that you, the application developer, need to react differently to many of these responses. Here is the current list of Twitter API response codes:

• 200 OK: Success!
• 304 Not Modified: There was no new data to return.
• 400 Bad Request: The request was invalid. An accompanying error message will explain why. This is the status code will be returned during rate limiting.
• 401 Unauthorized: Authentication credentials were missing or incorrect.
• 403 Forbidden: The request is understood, but it has been refused. An accompanying error message will explain why. This code is used when requests are being denied due to update limits.
• 404 Not Found: The URI requested is invalid or the resource requested, such as a user, does not exists.
• 406 Not Acceptable: Returned by the Search API when an invalid format is specified in the request.
• 420 Enhance Your Calm: Returned by the Search and Trends API when you are being rate limited.
• 500 Internal Server Error: Something is broken. Please post to the group so the Twitter team can investigate.
• 502 Bad Gateway: Twitter is down or being upgraded.
• 503 Service Unavailable: The Twitter servers are up, but overloaded with requests. Try again later.

Successful requests are easy to deal with, it is the error responses that always cause problems.How do you know what is an error and what is not? First, since we are dealing with basic HTTP requests, look at the list of potential response codes. For this discussion, I am going to ignore the Informational responses, codes 100, 101 and 102. I am assuming that most social APIs are not using those. What about the others?

Success Responses (2xx)

There are 8 possible success responses (200 through 207). Just like the Informational responses, only a limited set are likely used in the social media space. I have only seen two success responses used in the APIs I have reviewed:

• 200 OK: Obviously, this is a good thing and your application should handle the response data however it was meant to.
• 204 No Content: This is not a typical success response, but I have seen some services use this for searching to note that your request was successful but returned no results.

Redirection Responses (3xx)

These response codes are the initial reason for my writing this post. Typically, new sites tend to ignore redirects or have not figured out the “process redirect” options required for their communication library of choice. If redirect responses are not handled appropriately, your application can seem unstable or unreliable. Another interesting note is around those frame bars that some sites use like Digg, HootSuite or StumbleUpon. These bars have seen a lot of discussion around what redirect they use, due to the SEO implications of a temporary or permanent redirect. Again, there are only 8 possible responses, and I have only seen a few of those used:

• 301 Moved Permanently: Typically you will not see this in a social media API, unless they have changed their API. If you deal with website URLs or RSS feed URLs than this becomes much more important. This means the URL has moved permanently and you should check the header information to determine the new location and update your local records.
• 302 Moved Temporarily: This is now described as Found, but I am using the description people are more familiar with. As with the 301 redirect, you typically do not see this often in APIs except where something is changing for a short period of time. These redirects should be followed, but you should not be planning to change anything in your application. HTTP 1.1 added 303 See Other and 307 Temporary Redirect to help differentiate between several use cases, but I have not seem them used in APIs yet.
• 304 Not Modified: This is not exactly an error, but it is not the same as success either. Most likely your application can just do nothing unless it expected to receive something.

Client Error Responses (4xx)

You, the application programmer, did something wrong in order to receive one of these responses. Client error responses is also the largest group of responses with 27 responses in total. Obviously, I am not detailing all of them, just the common response codes.

• 400 Bad Request: This should not happen in your deployed application. You should be sending valid requests, but this is likely due to some user entered data. Make sure you are properly escaping all parameters to the API.
• 401 Unauthorized: It looks like you needed to authenticate before making your request, so make sure you do that. For public APIs, it could be that you do not have access to a premium API or some other security error.
• 403 Forbidden: Hopefully, the API provides a message in the response because this error is not specific to anything. I have seen this used as a security error as well. It is meant to be a more general authorization error that authentication will not fix. In many cases, you want to review the error and you may need to handle the situation with the API provider.
• 404 Not Found: Whatever you are asking for is not there. In the example of twitter, sometimes user accounts or specific tweets are deleted and you can get this problem. There is nothing wrong with your request, so just fail gracefully.
• 406 Not Acceptable: Twitter is using this for a bad result format being specified, so this kind of issue should not occur if you have done some testing. Bad parameters should be caught during various testing cycles. Twitter’s usage is in line with the specification, where you have requested a format in the Accept header that the application cannot provide.
• 410 Gone: This is just like a 404 Not Found response, but you are not supposed to ask for the URI again. APIs that are no longer supported could return this type of message, but more likely is a 404 Not Found.
• 420 Enhance Your Calm: Rate limits are being implemented in almost every social API now. So, you need to slow the number of requests you are making. According to the specification, 420 is not a valid response code but since APIs are not meant to be HTTP servers it is possible that your favorite API has a few custom codes as well.

Server Error Responses (5xx)

These are the responses you hate to see, but as a client application you need to properly handle them. There are 11 server error responses, and all of them basically mean something terrible has happened. Handling of these errors is very important as some HTTP client libraries could throw an Exception or Error, and your application would need to catch these situations and handle them appropriately. As with the other response codes, I have only seen a few of these used.

• 500 Internal Server Error: Something somewhere did not go right. For this error, review the API documentation for possible error codes or messages and act accordingly. Twitter only responds this way when something goes very wrong, but Digg uses this response for a bunch of error cases.
• 501 Not Implemented: This should not happen in a deployed application, but it is possible. Not Implemented is supposed to mean that the server does not recognize the request method. It is possible that an API would respond to unknown requests with this response, but I have typically seen a either a 404 Not Found or 500 Internal Server Error response.
• 502 Bad Gateway: Twitter uses this to notify people when it is down or being upgraded, but Digg does not use it. So, this is another case where you need to review the API documentation and figure out what to do. The only other times I have seen this is when the Apache HTTP server does not receive a proper response from the Tomcat server it is proxying.
• 503 Service Unavailable: Typically this means that some server is up, but not handling requests for whatever reason. This may not to be an API response as much as a server response. Similar to the 502 Bad Gateway response, a typical scenario is when the Apache HTTP server is running, but the proxied Tomcat server is down. The only good way to handle this situation is to fail gracefully and limit the number of requests to that server until requests are successfully handled.

So, if you are making HTTP requests, be prepared to have a significant amount of error handling. In addition to reading a lot of documentation on the API services that you are using, you need to read the documentation on how your HTTP client library handles the various response codes. Successful requests are easy to handle, but good redirection and error handling can make your application more stable and more reliable.

http://static.zemanta.com/readside/loader.js