Over the weekend I was writing code to consume some web APIs. The project sounded like fun and on a whole it will be. The problem came when I actually took a look at the APIs. They were built in a way that made me think about walking away from an otherwise fun project. Yikes. This is not good.

This got me thinking, what makes a web API the kind a developer wants to consume? What types of things, beyond the service being useful, make a difference? Three things came to mind that make a difference for me.

Start With REST

There are a number of ways to offer up content. REST, XML-RPC, and SOAP are just a few that come to my mind. It would be great for all 3 of them to be offered up. But, REST is where the API should start. REST is what the Internet is built on. Yahoo, Google, and the other big boys are using REST for a reason.

I know some developers want to go to SOAP first for their APIs. Think about it this way, Google had a SOAP API but dropped it years ago. Yahoo, Facebook, Twitter, and Google aren’t going after SOAP. They are going after REST. SOAP is still fairly popular in enterprise. In the Web API game REST is the current ruler.

Popular Language Examples

When if comes to the most popular languages used on the web PHP, JavaScript, and Python are the most popular languages. For web APIs to be consumed by the masses there should be tutorials for these languages.

Even if an application is written in .NET using C# there should be client libraries or examples in the popular programming languages. I don’t mean that they need to be written by the organization. Maybe just helped along, encouraged, and shared by the organization.

Easy To Get A Key

Ever have to contact someone during business hours to get an API key? Maybe send off an email and sit and wait? That time waiting is not only painful for a developer may could easily delay a project. What if the person developing is on the other side of the world? After all, the web covers all time zones. Or, the developer starts work on a weekend night. Waiting until the next week to get API access could delay the project more than a few days.

Yet, in the past month I’ve seen multiple examples of it being hard to get an API key for a web API and organization wants people consuming.

API Keys should be easy to get access to without ever needing to talk to another person. Just go into a control panel (nicely labeled) and get it. If they cost it should be automated billing and setup.

All Three of these bit me on a recent project. A mini storm that makes it difficult to want to develop against the API.