Flaws in RESTful response codes

Anyone that uses or develops APIs is familiar with REST. It is widely used and by some developers considered superior to other ways of doing APIs. Since REST was developed alongside the HTTP 1.1 spec, HTTP status codes are generally used for responses to REST calls.

To me, it seems that using the standard HTTP response codes (a nice list is given here) is overloading a standard server response with the response of a query. While the spec says that for client errors (400 series errors), the response should contain the reason why in the response. I've looked at a lot of APIs and the best ones at handling errors return the error response inside of a successful 200 HTTP response. For instance, if you are creating an API for dealing with support tickets and you ask for a ticket ID that doesn't exist or you don't have permission to access, returning a 400 series error generally tells the client that something bad has happened when, in fact, the error is kind of minor. Embedding the error in the response seems like a better way to go.

The problem, however, with embedding the error in the response is that the API developer has to come up with his own error codes and convey that to those that use the APIs. Many developers that implement APIs treat anything but a 200 series response as a complete failure and give up. So, the API developer has to make sure that the client implementors properly handle the responses. In general, I find it easier to have one set of parsing code and deal with the errors inside of a successful response.

My argument, of course, is not very compelling as it is simply to swap one way of handling responses and errors with another. Last night, however, I came up with a potential argument that leads credence to what I'm saying. If there is a proxy server or a load balancer in front of the server, it could potentially return an error code which the client may not expect. Let's take the case where our support ticket server is behind a proxy server and the client requests a particular ticket. If the proxy server or load balancer is misconfigured and we make a request, the proxy server could return a 400 series error, even a 404 error. The client could interpret this as "the ticket doesn't exist". This may not be the case; the ticket could exist, but the proxy returned an error. A better way of handling this would be to use 200 series status codes when the request succeeds and embed the API error code inside of the response. If the proxy server returned a 400 series error, the client could always treat it as an error and wouldn't have to figure out if the support ticket really existed or not.

In addition, the HTTP status codes are not granular enough for many APIs. This would require the API developer to have a secondary set of error codes that would be returned with the 400 series error codes anyway. If that is the case, why not just create one set of error codes and always return 200 series success codes unless something major has happened?

I know that some of this may be confusing (it is crystal clear in my head), but it is worth some thought to consider the best way to handle response codes in APIs. Many people have opinions on this and may think that I have no idea what I'm talking about and HTTP response codes are perfectly fine for RESTful APIs.

Wrong definition of a pioneer?

The other day I was looking at a website of a contracting company that specializes in mobile development. The site said that they were pioneers in the field. The site then had as its next line that the company was started in 2009. I normally think of pioneers as people who initially settle an area or who are first in a particular field. Unless my history of mobile is a little off, 2009 is a bit late to the party. If we just consider the "modern" era of mobile development that began with the iPhone and Android, they are still late as the iPhone was released in 2007 and the SDK in 2008.

However, saying that mobile development began in 2007/2008 is doing a disservice to all the predecessors to iOS. PalmOS came out in 1996, the Newton came out in 1993, Windows CE came out in 1996 and the Psion was about the same time.

I have no idea what meaning of pioneer this company had in mind, but they are certainly not pioneers in mobile applications. I've been writing mobile applications since 1994 when I first got a Newton (the Apple Personal Interactive Electronics group which made the Newton licensed my NotifyMail program and sent me a Newton MessagePad 110 in exchange for the license) and I don't consider myself a pioneer. I know a number of people that wrote mobile applications prior to this.

If the company considers themselves pioneers, what do they call their developers that have 1-2 years of experience? Experts?

The wrong way to use asserts

One of the ways programmers use to help ensure that inputs to methods are correct is to use asserts. Basically these will test conditions and stop execution if a test fails. By default, Xcode suppresses these asserts in release builds so that the code will simply continue.

This past weekend, I was helping out on a project and found that the app stopped because of an assert indicating that a condition was not satisfied. As I looked into it closer, the programmer had put in asserts to test the results of what came back from the server. The author then didn't do runtime checks to validate the data, he simply assumed that if the assert passed, that the data was valid and continued. The problem is that, in this case, the server returned data that the code wasn't expecting, so in a release build, the code would have continued and then crashed because the data wasn't in the correct format.

While I'm not a huge fan of asserts, they do have their place, just not here. The code should have done runtime checks and gracefully handle bad server data.

I suspect that the author hadn't done enough client-server communication to know that servers return bad data more often than you'd expect. I've worked on so many projects where a simple server change causes clients to have hiccups, that I've gotten pretty good at defensively programming against this.

If you choose to use asserts, make sure that you also use runtime checks and gracefully handle conditions that you test for in the asserts as the asserts go away in release builds.

First Week Review: Pebble Smart Watch

Two summers ago, the battery on my watch stopped, so I replaced it, but then found that my watch stopped again within a few days. I gave up on my watch and decided that I didn't need a watch as I have my phone with me all the time. Fast forward to last April when the Pebble smart watch appeared on Kickstarter. I was getting tired of having to pull my phone out of my pocket, so I became interested in it. The watch had 2 features that interested me; one it tells time and second, it would tell me when the phone rings. I've found that when my phone is in my pocket, I miss calls; people don't call me all that often, but I like to answer the calls. These 2 features sold me on the watch.

When iOS 6 came out, it added a Bluetooth profile called MAP which allows messages from the phone to the watch. This sold me even more on the watch.

So with these 3 features promised, I waited and waited (just like everyone else) for my watch to be delivered. Before receiving it, I read mostly positive reviews, but some negative comments. For me, I just wanted these 3 features and almost didn't care about anything else. From reading the specs and what people had to say, they indicated that the watch was big. I wasn't too concerned about this as I actually wore a Fossil Palm OS watch which was huge!

Now that I've had the watch a few days, I have mixed feelings about it. It does everything that I wanted it to do in terms of telling the time, letting me know when a text message arrives and when I receive a phone call. I've gotten some other notifications and now I want more; it appears that iOS only consistently notifies for messages, but inconsistently with other notifications. Pebble has documented a dance to get other notifications working, but that doesn't seem like a very good answer. Given that MAP support in iOS 6 is new, maybe Apple will add options to specify exactly which notifications will get passed through to MAP in the Bluetooth settings for the device as seen below.

The watch isn't the prettiest or cheapest watch on the market, but for the moment, it is fulfilling a need for me.

Pros

• It tells time.
• It lets me know when I get SMS or iMessages.
• It lets me know when the phone rings.

Cons

• It's big.
• Notifications other than SMS/iMessage/Phone are inconsistent (apparently an iOS 6 bug/issue).
• Drains the iPhone's battery a bit by having Bluetooth connected all the time.

Summary

If style is a main concern of yours, don't get this watch. If you want a completely bulletproof product, don't get this watch. The Pebble team is releasing updates fairly often to work out kinks and I think it will still be awhile before everything is worked out and issues settle down (like getting Apple to figure out what to do with notifications and MAP; there is a jailbroken hack that fixes this, but I'm not jailbreaking my device). The jury is still out of the watch's battery life, but it doesn't negatively affect my iPhone such that I'll probably be buying a Mophie juice pack Helium.

I'll definitely be wearing the watch while I wait for something better to come along; the rumors of an iWatch are interesting, but don't sound like a product Apple will bring to market anytime soon.