Recently I tweeted as a #linktuesday link the 10 Worst API Practices post from ProgrammableWeb. Today, in search of some concrete examples of APIs implementing unhelpful antipatterns, I sent out a tweet for help:
What's the most frustrating inconsistent/misleading bit of API you've seen? Looking for cautionary tales! Please RT In the raft of responses (and thankyou all, this was fabulous, helpful and entertaining in equal parts!), there were some definite patterns that I'd like to share with you, in no particular order.
The Patently Untrue 200 Response
This got plenty of mentions, and it's definitely a pet hate of mine!
@ response codes that don't match the content. i don't want to see a 200 when something has gone wrong or is missing! @ HTTP 200 with "X-MailChimp-API-Error-Code: -90" header ... @ in general: the ever classic 200 response with a text body explaining that the request actually failed @ HTTP 200 with a body containing "NOT FOUND" or "ERROR" @ in the body of a response with HTTP status 200 OK A Consistent Case of Complete Inconsistency
These aren't all the same complaint but they are basically the same problem!
@ APIs that have different urls for collections vs. items in collection: /issues vs /issue/157. So hard to remember to C-h. @ How about order sensitive XML? (yes, really), or SOAP which takes an XML package as an argument. /cc @ @ Collection end points that return an array of items if more than one, but return a single item itself if only one. @ API's with nutty error handling - sometimes HTTP error codes, sometimes special "envelopes" for error instead of data, etc. @ http://t.co/fQ6LXveJ: APIs which use a "method" parameter and mix German/English in the method names Documentation From a Parallel Universe
Is no documentation better than inaccurate documentation? I'm never really sure of the answer, but it does seem like a common problem.
@ @ Facebook's API is probably the worst I've had the misfortune of using. Their documentation is a mess too. @ Facebook API's are a world of joy. Documentation is more marketing speak than actual tech docs. Data types are not really spec'd @ paypal for sure, seems like even its maintainers somehow lost control over the different versions of docs and api @ some examples: implicit wrong-context escaping (Twitter), serving improper Content-Type, XML-within-JSON. Also: incorrect docs. @ @ incorrect docs+++ I think I'd rather have NO docs for an API and try to fiddle with it than wrong docs! @ facebook. mostly because of the ever evolving aspect without any clear docs or information policy So there you have it, the sins to avoid in your own APIs. If you've encountered any of these, please accept my condolences.
Love this post. I was also impressed with how neatly the tweets are laid out and displayed with their respective borders. How did you insert those? It's obvious that you didn't just take screenshots...
I use the "Blackbird Pie" plugin for wordpress to create those tweets, fabulous for quoting twitter content!
With respect to 200 codes, I'd love to know the context.; I've been using a heavily modified jquery.tweet.js on my tweet feed on my site and it turns out that jQuery JSONP just drops anything that's not a 200 OK and puts a generalised error message in the console.
This does mean that when I've been testing/refreshing a lot and Twitter decides I've overrun my allowance (or if anything else goes wrong) I have to copy/paste the URI in the error message to find out what's happening for sure by getting the perfectly well formed JSON as raw text.
Sometimes, just sometimes, the apparent loopiness of an API can be there as a painful workaround to combat a shortcoming in something outside the creators' control.
Dealing with telcos, I've seen all of this, often at the same time.
You have my sympathies!
Pingback: Links & reads for 2013 Week 3 | Martin's Weekly Curations
Pingback: Scott Banwart's Blog » Distributed Weekly 191