Specifications are probably the most important, completely ignored artifact I've seen in the developer world. Open source developers (including myself) swear by them, because they are a way to keep us all following the same rules. Yet, for a variety of reasons, they take a long time to adopt, and large companies have a tendency to just run over them whenever they become inconvenient. Worse yet, even when the specifications are revised later to make them work better, they continue to ignore them because now they have a backlog of code that ignores the specifications to work off of (See Internet Explorer). All this brings my latest cause of depletion of my Excedrin bottle.

OAuth is a specification for authentication between applications and server-side APIs. It's supported by most major internet APIs, though most of them are preferring OAuth 2.0 (Facebook recently forced all developers to move their applications to OAuth 2.0). You can find the OAuth specification here.

So why am I writing about this particular specification? Well recently I was working on a few outstanding issues on the ruby twitter gem (specifically Issue #161), which detailed a problem wherein posting a multi-part form with extra options in the body was causing an incorrect signature error to come back from Twitter. I sat down and traced it back to the generation of the OAuth signature in the middleware used by the twitter gem. I realized that it was throwing the entire body in the signature, except for the uploaded media. So I flipped open the specification and found that per section 3.5.2, the body should only be encoded if the content-type is set to "application/x-www-form-urlencoded". So I updated the code, made sure all the test cases ran, verified that it fixed the original problem, then checked to make sure that a few other commands were still working, then called it a day. However, upon review, @sferik discovered that this patch to the middleware had broken the normal status updating function.

Needless to say at this point I felt quite embarrassed, and doubly committed to actually fixing the issue appropriately. So I started going through twitter's development API to check how they were doing their authentication specifically. It was there I found out that Twitter encodes the entire body if there is no uploaded media, and NONE of the body if there is uploaded media. Obviously this is completely off specification (though I'll admit it is more secure than the specification way of doing it). I talked to the guys who run the twitter gem and ended up coding up a custom solution for the twitter gem to override the middleware's OAuth implementation, which resolved the problem.

But in the end I find myself conflicted about the entire experience. I understand that in order to facilitate a more secure environment for their users that the Twitter devs would want to encode the entire body for the majority of their interactions, however by going off specification, they're making it more difficult for all the other developers by forcing everyone to use custom solutions to deal with them. And anyone who's ever worked with CSS in Internet Explorer knows what kind of headache that can be.

So I guess in the end I'm curious what you all think? When is it appropriate to ignore the specification and code your own custom solution? Is it whenever you can do it better? When your company is large enough? When it threatens your clients? What's your tipping point?