How NOT to Design Your API

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:

[blackbirdpie id="289014953954930688"]

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!

[blackbirdpie id="289017133608882178"]
[blackbirdpie id="289017192115228672"]
[blackbirdpie id="289021466765320193"]
[blackbirdpie id="289021745887854592"]
[blackbirdpie id="289021973542096896"]
[blackbirdpie id="289022236214575104"]

A Consistent Case of Complete Inconsistency

These aren't all the same complaint but they are basically the same problem!

[blackbirdpie id="289019151597584386"]
[blackbirdpie id="289017655459995648"]
[blackbirdpie id="289019972712292352"]
[blackbirdpie id="289024964923908096"]
[blackbirdpie id="289027251675226113"]

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.

[blackbirdpie id="289017348516614144"]
[blackbirdpie id="289019749323653120"]
[blackbirdpie id="289021046164688896"]
[blackbirdpie id="289020763946749952"]
[blackbirdpie id="289020918041296896"]
[blackbirdpie id="289021114959663104"]

So there you have it, the sins to avoid in your own APIs. If you've encountered any of these, please accept my condolences.

9 thoughts on “How NOT to Design Your API

  1. 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...

  2. 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.

  3. Pingback: Links & reads for 2013 Week 3 | Martin's Weekly Curations

  4. Pingback: Scott Banwart's Blog » Distributed Weekly 191

  5. Pingback: Links & reads from 2013 Week 3 | Martin's Weekly Curations

Leave a Reply

Please use [code] and [/code] around any source code you wish to share.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>