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
- WordPress Style API Modules For Government
- The Heroku HTTP API Design Guide
- What I Have Been Calling API Trends, Are Slowly Being Baked Into API Operations
- FDA Finding Their API Mojo With A New Drug Label API
- Adding PokitDok To Healthcare Research And The API Stack (Well They Did)
- Why I Am Continuing To Integrate Zapier In My Business Workflow
- Who Is Going To Build The Uber API Platform For The Sharing Economy?
- The API Focused Dev Shop
- Route SMS Messages To Google Spreadsheets Via Twilio API With TwilioSheet
- Publishing Your APIs To Product Hunt
- Providing Users With Reciprocity Tools So Important Intuit Purchases itDuzzit
- Bing Developer Assistant for Visual Studio Delivers Relevant API Code
- Average Number of APIs Used In A Modern App
- An APIs.json Collection Of API Resources Across Your Public, Partner Or Internal Resources
- One Possible Reboot Of The API Stack
- How Are Dev Shops In Chicago Using APIs? A Talk With Bryson Pouw At Blaze Portfolio
- Every API Provider Should Have A Logo And Branding Page
- What Is An API First Strategy? IT architecture And Catalyst For Engagement
- The Speed Of Federal Government When It Runs On Github
- Swagger, APIs.json, And Review For The New Developer.Trade.gov
- Student, Instructor, Classroom, Class, And Course API Planning At BYU
- Can You Add My API To Your Website Listing?
- Adding Google To List Of API Deployment Companies
- What Is An API First Strategy? Adding Some Dimensions To This New Question
- The Five Month Journey Toward A Stable APIs.json Discovery Format