Posted on 06-27-2012
After looking at over 6000 APIs, the most irritating thing for me when reviewing an API, is when I have to work to figure out what an API does. Many APIs just don't communicate what their API does and articulate the value for developers.
Every API should have a quick introductory paragraph at the top of the first page that clearly defines the API in 250 words or less. Many APIs have a description, but it often reads like this:
The [Insert Company Name Here] API delivers programmatic access to all the features available in the [Insert Company Name Here] web application. Developers can use the API to build web and mobile applications using the functionality it provides.
Ok? You just told me nothing. I have no idea what your core web application does, or your API. The second worse offense I see API owners commit, is they get all RESTful on you:
The [Insert Company Name Here] API delivers RESTful access to the features available in the [Insert Company Name Here] web application. Using the API you can construct URLs and GET or POST information to the API and receive either XML or JSON responses.
Ok? You just told me nothing. You gave me a brief introduction to REST. Not very helpful. Often times I have to go to the parent website to figure out what a company does, before I understand the value of an API.
As an API owner, make sure and provide a quick, concise description of your API and the value it delivers. Don’t assume developers are in your head or understand what your company does. When writing your description, give it to someone who knows nothing about your company and see if they can figure out what it does.
I shouldn’t have to work to understand what your API does. Describe the value to me, quickly make me understand how it will help me, so I have the motivation to move past your main page, dive into your documentation and begin integrating.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- My Discussion Today With 6 Hypermedia Leaders At API-Craft in Detroit
- Getting To Know Jørn Wildt For The API Craft 2014 Detroit Hypermedia Panel
- Hypermedia Feels Like We Are Still Learning To Communicate With APIs
- Getting To Know Markus Lanthaler For The API Craft 2014 Detroit Hypermedia Panel
- Getting To Know Kevin Swiber For The API Craft 2014 Detroit Hypermedia Panel
- Getting To Know Steve Klabnik For The API Craft 2014 Detroit Hypermedia Panel
- New Indix API KickStart Program Reduces Costs For Developers
- Getting To Know Mike Kelly For The API Craft 2014 Detroit Hypermedia Panel
- A Shared, Distributed Experience(Metrics) Layer For The API Driven Application Stack
- Showcasing Your API Integrations With Other Platforms
- Increasing The Focus On APIs In Higher Education Is Important
- Getting To Know Mike Amundsen For The API Craft 2014 Detroit Hypermedia Panel
- The New StrongLoop API Server Provides A Look At Future Of API Deployment
- Models For API Driven Startups Built Around Public Data
- Will You Add Me To API Evangelist And How To Spot The Cool Kids
- When I Remix APIs Using Swagger How Do I Deal With Authentication Across Multiple APIs
- It Takes A Team Of Evangelists To Raise An API
- Support For Only Two Creative Commons Licenses In The API Commons
- Machine Readable Terms of Service Didn't Read Applied To APIs Via APIs.json
- API Deployment For Non-Developers Using Zapier, Google Docs, and APISpark
- State of Hypermedia Today @ API Craft In Detroit
- Need A Formal API Standard For Your Government Agency? Fork 18Fs, And Make It Your Own!
- CORS Makes Your API Portable And Remix-able
- Chief Data Officer Needs To Make The Department Of Commerce Developer Portal The Center Of API Economy
- An API Definition As The Truth In The API Contract