Web services and their APIs abound. Unfortunately, the vast majority are difficult to use. Reasons range from poor design, to lack of documentation, to volatility, to unresolved bugs, or in some cases, all of the above.
Follow the guidance in this post to help ensure that your web API is clean, well-documented, and easy-to-use. Such APIs are truly rare and are therefore much more likely to be widely adopted and used.