Over a million developers have joined DZone.

The Importance of Thinking Externally When Writing the Description for Your API

DZone's Guide to

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.

· Integration Zone ·
Free Resource

SnapLogic is the leading self-service enterprise-grade integration platform. Download the 2018 GartnerMagic Quadrant for Enterprise iPaaS or play around on the platform, risk free, for 30 days.

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. 

With SnapLogic’s integration platform you can save millions of dollars, increase integrator productivity by 5X, and reduce integration time to value by 90%. Sign up for our risk-free 30-day trial!

api ,integration

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}