Monthly Archives: June 2011

Why APIs suck!

APIs are the vain of all (maybe not all, but at least most) developer’s existence, mainly because they hate integrating with someone else when they could just do it on their own.  In my experience I have found this to be rather disheartening.  I however think I have found many of the root causes through the cryptic concerns that are expressed by developers.  It seems that either poorly built APIs (and what made them that way) as well as lack of understanding for both API developer and integration party of the purpose of the API are the root causes.  This is a rather heavy handed statement and I will be delving in depth into what the implications of this are from a development and theoretical point of view.

Contrary to what the developers say, APIs probably consist of some of the most useful lines of code in the computing world, other than your favorite OS of course.  There are multiple reasons for this.  Firstly, APIs prevent duplication of code (for the purpose of what the API does, not the client).  I’m sure one day I’ll discuss centralization of code and the problems and advantages with it; however, for the purpose of this discussion, integration with APIs reduces work on the developer.  By using something that somebody else has already built, you don’t have to do it yourself.  This seems straightforward in nature, but it seems that developers still tend to attempt to defy 3rd party integration for multiple reasons.

Developers push back against integration partly because interfacing with 3rd parties can be difficult, especially if API developers are un-supportive to integrators.  This is a rather stupid move on the part of the API developer as most of the time, it is the people integrating with the API who are the reason for the maker’s of the API to garner any sort of income.  To a developer, there is nothing worse than having to deal with a support group or developer that isn’t willing to help.  This creates a bad feedback loop, since the developer still has to move forward, but can’t get help, he then pushes forward on his own wasting lots of time on a task.  This issue can be hard to solve on behalf of the integrators part; however, it is easily remedied on the API maker’s part by assigning a resource (preferably one who helped build the API) to assist people with integrating.  The remedy to assigning a resource is good documentation.  Although it will never supplant a human resource to talk with, it doesn’t hurt.

Which leads me to the second issue on why developers hate interfacing with APIs, lack of documentation.  This is probably the greatest hurdle as to completion of integration with APIs and for obvious reason.  It is rather obvious that without documentation (and without source most of the time to study because it is 3rd party) developers don’t like going on fishing expeditions.  Theoretically, all process flows, function calls, parameters, expected results and errors should be well documented.  Often the only thing that comes out of documentation is the function calls and parameters through an auto generated system.  I am guilty of calling this documentation; however, it isn’t.  Is is just snippets of code with bold, underlines, and tables most of the time.  True documentation should fully explain what something does and how to use it, not just what it looks like.  This leads me into the final reason I think APIs are hated, lack of consistency.

Consistency is key I was always told.  This has no better application than when it comes to APIs.  Nothing pisses off a developer more than a field “user_name” on one call, and “userName” on another call inside the same API.  This shows that the API was either not well thought out, or built by several people who weren’t in communication during it’s construction.  There is no solution to this, and will be a nuisance as long as you use the API, or until they rewrite.  This is a hard problem to mitigate, and can cause many stupid mistakes that will cost time and money.

If you work with an API that commits two or more of the sins above, firstly I would like to offer my apologies, because the other party probably never will.  Also, I think it is time for you to find another API if at all possible.  By switching you will save yourself headache, find a good partner in business.

In the end I guess it just comes down to a few things.  APIs are critical to anything in development, and with even half decent human support, decent documentation, and a well planned consistent interface, APIs turn out to not be so bad.