All too often we'll receive a "specification" document which just lists a bunch of URL fragments with the word GET or POST next to them. If we're lucky, we'll get a sample of the request and response body.
What we're left with are the two problems you described. We have no idea how to actually _do_ anything with the API. And when things don't appear to work, we're left guessing.
What we're left with are the two problems you described. We have no idea how to actually _do_ anything with the API. And when things don't appear to work, we're left guessing.
Some of the best API "guides" are the ones that break things down by use case and describe how to achieve it. For example, I'm a fan of GitHub documentation: https://developer.github.com/v3/issues/#create-an-issue.