

Common Mistakes Made by API Providers - cgbystrom
http://www.readwriteweb.com/cloud/2010/08/the-new-api-movement-may.php

======
wccrawford
I found some unexpected wisdom, along with a lot of things I agree with.

"If you haven't built your website on top of your API, consider doing that --
or at least what it would be LIKE to do that. If your API couldn't reproduce
your website, your API needs fixing."

At first, I was going to argue with this. But then I realized: You don't have
to actually -do- it, just write like you would. You don't have to give third
parties the ability to do everything you can do locally, so long as you
program in such a way that it can be done. It helps decouple things better,
and make things more testable.

~~~
njharman
BBC (I think or maybe it was PBS|NPR) did this. Recent article talked about
how they decided to go "open" and put everything in API. Later on when
developing for satelite stations and other projects they found using their API
was the bestest, fastest way to go.

------
mootothemax
Twitter is the absolute best case study for this. I love that a response that
should return XML or JSON formatted data returns the fail whale in all its
HTML glory when they're overloaded. I still don't understand how in their mind
that's more efficient than a 503 http response.

~~~
cheald
Chances are that they've got something like HAProxy running in front of their
application backends, and you get a shirnkwrapped 503 page back when no
backend can be reached. In that case, the application can't intelligently
decide to return a json response because the application never gets the
request.

~~~
thwarted
While API clients should be able to interpret the HTTP response code, 503 in
this case, in a meaningful way, the API should have internal status/success
codes that the body of the 5xx responses can contain.

Using haproxy to load balancer is no excuse for this, as you can tell haproxy
to serve custom error documents using the errorfile option, and these error
documents can be json or XML. And you can use layer 7 routing in haproxy to
allow different configurations based on what the request looks like (in the
case of, say, you were dumb and put everything your site does on a single
domain, rather than putting the api on a different IP/subdomain).

------
ultrobast
Oh man, I wish the developers of the API I'm working with right now read this
(or just had any common sense at all). XML feed is a load of tab seperated
data held in one tag. Two, three or four API calls are needed to get all the
data I require (using unique codes from previous calls so there's no other
way) and when it sees something unexpected, as it wont to do since I'm passing
a tab-seperated mass of meaningless codes, it just dumps back the XML you sent
it. No error message, no stack trace - just exactly what you sent over before.
Kind of like a teacher handing you back some work with the "want to try
again?" speech.

------
CallumJ
The irony that Mashery contributed to this article is just perfect.

------
julien
It should be noted that in general APIs are a modern form of slavery! Build
something that depends on an API, and be exposed to any arbitrary decision by
this API provider. I think Twitter's decision to shut down HTTP basic Auth (in
favor of OAuth, which is great) is a perfect example of this.

I wish more services would implement open protocols, agreed upon standards
than just proprietary APIs.

~~~
mrduncan
_It should be noted that in general APIs are a modern form of slavery!_

I think that's a little over the top, nobody is forcing anyone to use their
API. If you rely on an API, you should accept that it can (and likely will)
change in the future.

Twitter has been pretty up front about the fact that HTTP Basic would be shut
off since they first released OAuth. I think they've done just about as much
as they can to help people move away from HTTP Basic.

 _I wish more services would implement open protocols, agreed upon standards
than just proprietary APIs._

I'm not sure what you mean by open protocols and agreed upon standards. HTTP
Basic and OAuth are both open and agreed upon.

~~~
Raphael
HTTP APIs typically use slightly different parameters, so there is no existing
support, as opposed to an established protocol, such as email.

~~~
gnaritas
I've read that sentence like 5 times, and it still doesn't parse. I have no
idea what you're trying to say there.

