I look at a lot of APIs, and one characteristic I judge them by, is their ability to simply explain what their API does. The most import aspect to any individual or company when doing APIs, is the process can potentially bring you out of your bubble, and make you think a little bit more externally.
One of the most common things I see from API providers, is they think it terms of, and present their API in the context of the language they program in. It is a ".NET Web API", or a Python API. When in reality it is a web API, and if it employs enough HTTP, it should be able to be consumed in any language.
Another regular mistake made by API providers, is they describe their API in terms of their own platform, and never actually tell you what it does. Here is an example of this from PushBullet:
Pushbullet's API enables developers to build on the Pushbullet infrastructure. Our goal is to provide a full API that enables anything to tap into the Pushbullet network.
While I appreciate the short description of what the API does, I'm left still not knowing what it does. You see, I do not know about Pushbullet like you do, and chances are neither will many of your other potential API consumers. Knowing about your company shouldn't get in the way of me learning about what your API does.
To me, this is classic walled silo-itis, where programmers are operating within their little company or tech silo, and don't look much further. That is ok, this is why we do APis, to help break you free of these cycles.
