The Importance of Thinking Externally When Writing the Description for Your API
Writing a description for your API? The most important factor is considering your external audience. Simply explaining what your API does goes a long way. Check out what's so crucial about a mere breakdown of your API's functionality.
Join the DZone community and get the full member experience.Join For Free
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 of 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 fromPushBullet:
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.
Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.