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.
blog comments powered by Disqus
Latest Blog Posts
- APIs in DFW
- Adding API Broker Under Monitoring for API Aggregators
- The Dark Matter That Make APIs Work
- Potential for API Aggregators to Provide Valuable Industry Data
- My Talk Tomorrow Night at the Dallas-Forth Worth API Professionals Meetup
- The White House Releases An Open Data Strategy
- When API Success Signals Begin Working Against You
- Get To Know Which Languages Your API Developers Are Using
- Twitters Developer Area is More Embeddable Than API
- Overview Of Backend as a Service (BaaS) White Paper
- Make Sure And Have Multiple KPIs For Your APIs
- API Enabled Toys For Our Children
- I Am Speaking At The Dallas-Forth Worth API Professionals Meetup May 14th
- How Much Do You Spend Attracting and Supporting Freemium API Developers?
- What Does The API Evangelist Do?
- Startups Need To Work Together on API Definitions
- Parse Is Successful By Truly Solving Problems for Mobile Developers
- API Commandment: Thou Shalt Not Forego Talking to a Person
- API Trends
- API Priorities
- Have You Taken A Look At AT&T APis Lately?
- Helping People Understand APIs Through Real World Examples
- Evolving Beyond API Service Providers and Tools to Goal Based API Toolkits
- APIs & The Federal Government
- After Last Couple of Weeks, It's Clear There Is Big Opportunity In The API Space