Dave Winer mentioned the problems he had getting the MetaWeblog API specification out:
BTW, while we're on the topic of APIs, here's something you might not know. When I put things like the MetaWeblog API up for review, the flamer-fans almost immediately drown out the discussion, so we're left with a spec that's not complete (but pretty good in the end). Then the very same people criticize the spec because it's not complete. Isn't that special.
I don't mean to single Dave out, but the entire blogosphere is built on APIs like MetaWeblog, the Blogger API, and ATOM, and the documentation and state of all of those specs leaves much to be desired. As for the MetaWeblog spec, I have no problem with it but there just doesn't seem to be one place to go for a coherent documented version. The Blogger API consists of a page of methods and expected parameters. The Atom API documentation consists of a page of HTML requests to send and the expected responses and very little explanation. Good luck figuring out why it is returning an HTTP 500 error.
The other day I spent 20 minutes trying to get MetaWeblog.newMediaObject to work, encoding the file in Base64 just like the minimalist instructions said. Just for fun I tried NOT encoding it, and it worked just fine.
These APIs, if you can find documentation at all, often don't work as advertised, and there is clearly no accepted standard. Writing a blogging tool should be a simple task, but it is made all the more difficult by the need to support the various flavors of specs and their idiosyncracies.
How much effort are we expending trying to deal with the problems we have created just because we can't agree?