Enterprise Integration
Enterprise Integration Zone is brought to you in partnership with:

Lorna Jane Mitchell is a PHP developer, blogger, trainer and evangelist from Leeds in the UK. She is active with phpwomen.org and her local user group PHP North West, and writes for a variety of outlets, including her own blog at lornajane.net. She is an active member of the PHP and open source communities and contributes to the joind.in event feedback project. When she's not at her computer, Lorna enjoys yarn craft, hobby electronics, and her home renovation project. Lorna is a DZone MVB and is not an employee of DZone and has posted 52 posts at DZone. You can read more from them at their website. View Full User Profile

How NOT to Design Your API

01.14.2013
| 11069 views |
  • submit to reddit

Related MicroZone Resources

Prepare for the New World of Integration!

Easy Legacy System Integration

Feature Chart: Mule ESB v. Enterprise

Use Your Java Toolchain with SAP

6 SaaS Metrics that Matter

Like this piece? Share it with your friends:

| More
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!
@rich_81
Rich Sage

@ HTTP 200 with "X-MailChimp-API-Error-Code: -90" header ...
@rdohms
Rafael Dohms

@ in general: the ever classic 200 response with a text body explaining that the request actually failed
@lsmith
Lukas Kahwe Smith

@ HTTP 200 with a body containing "NOT FOUND" or "ERROR"
@NunoFrancoCosta
Nuno Costa


@ in the body of a response with HTTP status 200 OK
@andriesss
Andries Seutens

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.
@mwop
weierophinney

@ How about order sensitive XML? (yes, really), or SOAP which takes an XML package as an argument. /cc @
@thejmather
Jacob Mather

@ Collection end points that return an array of items if more than one, but return a single item itself if only one.
@akrabat
Rob Allen

@ API's with nutty error handling - sometimes HTTP error codes, sometimes special "envelopes" for error instead of data, etc.
@auroraeosrose
auroraeosrose

@http://t.co/fQ6LXveJ: APIs which use a "method" parameter and mix German/English in the method names
@hochchristoph
C. Hochstrasser

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.
@jpaylor
Jonathan Paylor

@ Facebook API's are a world of joy. Documentation is more marketing speak than actual tech docs. Data types are not really spec'd
@wardbekker
Ward Bekker ✅

@ paypal for sure, seems like even its maintainers somehow lost control over the different versions of docs and api
@DJCordhose
Oliver Zeigermann

@ some examples: implicit wrong-context escaping (Twitter), serving improper Content-Type, XML-within-JSON. Also: incorrect docs.
@coates
Sean Coates

@ @ incorrect docs+++ I think I'd rather have NO docs for an API and try to fiddle with it than wrong docs!
@auroraeosrose
auroraeosrose

@ facebook. mostly because of the ever evolving aspect without any clear docs or information policy
@lsmith
Lukas Kahwe Smith

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

Published at DZone with permission of Lorna Mitchell, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Roger Sall replied on Tue, 2013/04/09 - 1:15pm

 body of a response with HTTP status 200 OK

blogeral

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
"Starting from scratch" is seductive but disease ridden
-Pithy Advice for Programmers