At Arcturo, we’ve been working with a lot of remote API’s and big data lately. The more API’s from all over the web I work with, the more I realize how much some companies really get how to build an API that developers love and use all the time, but at the same time, I’m beginning to realize how little thought some teams really put into their API and how it will be used. I rant about this often to Ryan, so I thought I’d go ahead write up a little list of things that API consumers would really appreciate if you’re providing an API.

Keep it consistent.

The number one most annoying thing I’ve encountered is inconsistent treatment of API calls. For example, let’s say I’m working with an API to a library. If I pull a book from the main collection and then a book from the reserve collection, both should contain the same citation information. If both of them, from my end, look like a book but contain different information (or annoyingly differently formatted information), that’s a big usability problem.

Much like we obsess over the user experience on the client side, investing time in your API’s user experience will yield big results in terms of adoption and engagement from developers. Think about what they will be doing and make the path from where they are to where they want to be as frictionless as possible. Giving me inconsistent data is a huge blocker to actually getting things done because not only am I wrestling with the data itself, I’m also trying to figure out what your assumptions about the data are and how they may affect something else I’m doing.

Make it general.

I can’t count how many times I’ve talked to teams who are building an API for internal use and are “just going to give people access to that.” While that turns out well sometimes, in general your internal product, case-specific logic will end up being more annoying to someone attempting to adopt it.

I was working with an API once that kept returning boolean data in different ways among the different calls, and when I inquired as to why that was, I was told that their iPhone app interpreted the data one way, their internal web services another way, and the Ajax calls they were making a different way. Of course, I was building something that cross-cut all the calls used by these services, so it made my life incredibly difficult (I literally eventually built a BooleanParser class or some such silliness to handle all the different states). If you’re building an API for something internal, then keep it internal; just because you can offer an API based on some internal thing doesn’t mean you should!

Keep your information up to date.

Please. Please. I’m begging you. The first thing you should do after changing anything in your API is to ask “Has then been documented and/or covered in our client libraries?” Having your API documentation being out of sync with your actual running API is a death sentence. This situation is becoming more and more of a problem as more sites are adding API’s as a second thought rather than a core functionality. Go ahead and compare your average web application’s API documentation to someone like Twitter who have made their API a core competency (though I could offer them as a counter-example to that about 2 years ago…).

Even more important is to make sure that the code developers are running and working with jives with what you’ve got running on your servers. If the documentation is wrong, that’s not such a huge deal if I can dig around in your client’s source and figure out what changed. But if the client is wrong and the documentation is right (or both are wrong), you’re going to drive me to Bedlam before I figure out you haven’t updated something. Keeping your API releases synced with documentation and client releases will go a LONG way to keeping your API users very happy.

Don’t gimp it.

If you offer an API feature, offer to your clients evenly. I understand “premium API features” and all that jazz make total business sense. I’m all about people monetizing their API’s as much as it makes sense. Where I think you, as a provider, cross a line is offering certain API’s only to your in-house, product bound clients and no others. Not only is it sort of gratingly protectionist to the point of turning off a lot of potential developers, it just doesn’t make any sense. If you’re going to arbitrarily limit the ability to which I can engage your product via the API, you obviously don’t want my competition or my contribution to your ecosystem very badly.

I understand limits in terms of not allowing blatant scraping of data or something that’s core to the viability of your business, but disabling convenient features and neat additions in the name of arbitrary limits is a problem. Twitter, while being fantastically open in a lot of respects, really put a bad taste in developers’ mouths with the whole OAuth/XAuth split for example. Limits like that can easily build up a lot of bad press and kill developer goodwill for very little benefit.

Be prepared for customer service.

As API usage grows, developers will inevitably have questions, requests, problems, and want to chat about their favorite beers from this really cool microbrewery in South Carolina that you just have to try when you get a chance ZOMG. Many API providers simply tell a couple of their developers to answer all of these inquiries just sort of as they have time between all the Real Important Work™. E-mails and support tickets pile up, people get upset, and things explode. No one wants that.

Instead, be prepared to offer actual customer support. Even if it’s one developer whose primary workload is flipped (answer support inquiries first, fix bugs and add features second), then that’s better than treating your existing developers as second class to building stuff. Your developers will thank you and sing the praises of your API team all over. Look no further than Twilio to see this in action; these guys really get it in terms of working with developers directly to make sure they succeed.

TL;DR

Your API developers will appreciate you at least considering their sanity in how you build and operate your API. Thanks.