"12 Reasons Your API Sucks" was the other talk by Keith Casey I saw at this year's Code Camp.

So, what are the twelve reasons?

1. Documentation. PDF documentation has maintainability issues. Move documentation out of PDFs to your web site. Don't hide documentation behind an NDA. The documentation needs to be discoverable. If people are googling your error messages and finding Stack Overflow instead of your web site then others are writing your documentation for you.
2. Helper Documentation. This is not the same as API documentation. Give the best documentation possible at the lowest level possible (i.e. that is, don't shut others out by giving language-specific details.)
3. "Getting Started" Code. The examples need to be good, short, terse.
4. Too Much Boilerplate. Don’t have examples 22 lines long.
5. SOAP as the Interface. SOAP is like a mortgage with a big contract upfront and a multistep process for reacting when things go wrong. REST in contrast is more flexible and hence better though it does introduce ambiguity to iron out.
6. Illogical Inconsistencies. Getting "201 Created" back from a resource is an example.
7. Poor Workflow and Modeling. The entire point of an API is to offer affordances, just as the handle on a coffee mug affords the ability to pick a coffee mug up by hand or perhaps hang the coffee mug on a peg. On the other hand it is hard to see what the Twitter and Facebook APIs afford and what they were intended for and this wishy-washiness is a bad sign. Twitter put a lot of companies out of business when it turned off its API and this pain stems from murkiness in definition of goals.
8. Numerous Approaches. If there are too many ways to approach how to do something and no one way is right, that is and things are confusing.
9. Authentication. Don't roll your own. Unless you are a cryptography expert you'll do it wrong. Find a plugin or a module in your space.
10. Your Stuff is Broken. What does your uptime look like? 99% is fine for Dish Networks. For you? Is your API Deterministic? Does it return the same result every time for each input? It really should because if it doesn't it will give the impression that it is broken. At Clarify, where results are based on voice-recognition and hence have a hint of play, data handed back is kept at a database and all queries are looked up against existing records to make sure that back to back requests for the same content do not return varying results enraging the users.
11. Error Messages Are Bad. 404 is an error and not 200.
12. Logging and Debugging. Runscope was recommended as a tool to use.