My experience is similar to a lot of others. I've spent the last two years working with quite a few social media APIs and while Twitters API documentation and reliability could be a bit better at least it looks like there was some level of design/thought to it. On the other hand is Facebook, which to say appears to have come into existence organically would be beyond generous. Examples are non existent, bugs are either unacknowledge or unfixed indefinitely and documentation as simple as what permissions are needed to access a property are a challenge to find.

In general APIs are going to suck unless you're paying to access them. It may be less than perfect, but being able to ride on the coattails is better than nothing.