Over a million developers have joined DZone.

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

Build APIs from SQL and NoSQL or Salesforce data sources in seconds. Read the Creating REST APIs white paper, brought to you in partnership with CA Technologies.

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. 

The Integration Zone is brought to you in partnership with CA Technologies.  Use CA Live API Creator to quickly create complete application backends, with secure APIs and robust application logic, in an easy to use interface.

Topics:
api ,integration

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

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

{{ parent.tldr }}

{{ parent.urlSource.name }}