What Drives Me Crazy When Integrating With a New API?

by Kin Lane on 09/08/2012

I was directed to an API question today, that needs to be asked constantly in the space:

What’s your biggest web API pet peeve? What drives you crazy when integrating with a new API?
— Wynn Netherland (@pengwynn) September 8, 2012

My response was:

Reply to @pengwynn my top 4 R 1) incomplete or cumbersome docs 2) lack of code samples 3)senseless rate limiting 4) no self-service reg
— Kin Lane (@kinlane) September 8, 2012

This is such a relevant topic I wanted to continue the conversation by listing the top 10 things that drive me crazy when integrating with a new API:

Incomplete or Cumbersome Documentation - Definitely something that will keep you from a achieving a successful integration and make you walk away from an API
Lacking Code Samples & Libraries - The programming language i’m using could vary from project to project, and the code samples and libraries can make or break my successful integration
Senseless Rate Limiting - Rate limits are an essential part of API management, but placing of rate limits unecessarily and without pressure release options, doesn’t make sense
No Self-Service Registration - As a developer, I need instant gratification. I need to know if an API will work for me, and getting started immediately will make the difference between using and walking away
Reliability - I’m depending on an API, if its not reliable, I can’t depend on for my application. There are many aspects of API management that goes into reliability--spend the time to understand what it takes
Terms of Use - Nothing stops a great application idea more than restrict terms of use. Make the legaleze as developer friendly as you can
Communication - Regular communication with developers goes a long ways. Whether blog posts, tweets or working with developers in person at hackathons, communication is an essential for me to adopt an API
Usage Analytics - As a developer I need to understand how I’m using an API. As an API owner, you should be tracking every aspect of API operations, make sure and share some of this insight with developers
Business Model - A business model for both API provider and consumer is essential for a healthy API experience. If the API provider isn’t making money or delivering value, it’s not sustainable--if the developer can’t pay the bills, their integrations will not survive
Clear Pricing - If I don't know what it will cost for me to accomplish what I need with an API, there is very little chance I will integrate it into my application. I've become very accustomed to knowing my AWS bill, with the clear pricing they provide

All nine of these items go into establishing trust between API provider and consumer. There are some APIs I just trust and others I don’t. Delivery in these nine areas, all feed into whether I trust an API for my business or not

I depend on 21 separate APIs for my business. I’m working to add more to this stack, and as a developer I can identify if an API has value within seconds, and hopefully have it integrated with in minutes or at the most a couple of hours.

As an API provider, make sure and find out what drives your developers crazy while integrating, and see what you can do to reduce friction in these nine areas.