I have noticed a trend with regards to API/ Web service design, mostly from those where the API has been tacked on as an afterthought. Most API’s have some form of documentation listing where the request and response fields are outlined. This is a good start but then they don’t list when the possible return types are and any corner cases where you can’t request certain things with other things.
This is probably down to being short of resources or knowhow when constructing a fairly simple, possibly low use API, but almost ensures that anyone who wants to implement it properly will be contacting them for more details, occasionally the company themselves don’t know why their API is behaving in a certain way.
I have also noticed some using WSDL in a way that doesn’t really actually specify anything by leaving the return type open. I’m no real fan of SOAP but at least a proper WSDL can go a long way to figuring out how an API will behave.
I think a bit of extra time to fully document an API will save a developer/ support staff a heap of time down the track where other developers are able to implement their API without ever getting in contact. At very least though, when you get questions from developers the answers should also go into the docs so the same issues are covered in future.