Recently, I decided to build a small application that interacts with the Twitter API, the cli.gs API and Google Calendar to allow me to get advanced notice of any and all Boston Celtics games. The app is actually live and can be followed on Twitter.
It’s a pretty neat little application that runs on a daily cron job and queries a small database to see if there is a Celtics game on the following day. If there is a game the next day, it generates a link to add the game to Google Calendar, shortens the link using the cli.gs API and sends out a Tweet with the game details and Calendar link. Pretty sweet, right?
Unfortunately, almost immediately after going live the Twitter API started to return some nasty HTTP responses and I was unable to update the status of the celticsgames account. Specifically, the Twitter API started to return the HTTP 417 response code. After doing a little Googling, I found that I was not the only person using the Twitter API to suddenly (and without any warning) run into a problem that broke their application.
The issue stems from the inclusion of the HTTP Expect header in the request that is sent to the Twitter API. I’m using PHP and cURL to interact with the Twitter API. Apparently, this header is sent by default with a value of ‘100-continue’ by cURL (unless you override it and set a different value). Seems the Twitter API grew very confused by this setting in the past few days. The HTTP spec states that:
A server that does not understand or is unable to comply with any of the expectation values in the Expect field of a request MUST respond with appropriate error status. The server MUST respond with a 417 (Expectation Failed) status if any of the expectations cannot be met or, if there are other problems with the request, some other 4xx status.
I did some checking and I can’t find any mention on the Twitter API Wiki about a recent change that would have affected how the Twitter API responded to HTTP requests with the Expect header set in any particular way (it is possible, though, that I could have missed it). I also referred to the specific list of HTTP status codes returned by the API — no mention of a 417 response at all.
In my opinion, this is a pretty crappy way to manage an API. If your goal is to encourage third-party developers to build applications that work with your API, don’t make breaking changes without going to great lengths to ensure the developer community understands how the change will impact them. And for goodness sake, update your documentation.
Fortunately, there is a Celtics game on later today (during which they will absolutely pound the LA Lakers) — that should take this bad taste out of my mouth.