By on July 28, 2012

5 tips to designing an API the Right Way

Everyone is building APIs these days. Most new apps/services have some kind of API, and almost every app uses at least one API. I was hacking on a project a couple of years back, and I remember one of the developers on the project mentioning that we should have an API. At that time, I thought he was crazy. We have not even launched the product, why would anyone want to use our API, let alone our App? Our app eventually failed, mostly the fault of ourselves. We out grew it, moved on to bigger and better ventures, but looking back, he was right. We should have had an API. It may not have failed.

When you start to build your API, ask yourself, is your app going to be valuable to someone? Are you solving someone’s pain point or are you adding to the noise? APIs like Twillo, Stripe, Salesforce, Dropbox and Twitter add value to the world. Is your API going to be a service like Twillo or Stripe, where your core business is providing core level functionality to someone else’s app? Are you going to build an app with the goal of having people add value to your product, like Twitter? Someone will likely not want to use an API if it adds no value to the community/world.

A great API is planned and designed well. Two questions you should be asking yourself when designing your API are:

  1. What are the goals or goal of this API?
  2. Who will be using this API?

You need to start asking yourself questions like what protocols and data formats are you going to use. How are you going to lock down your app? Use an open source framework or build it from the ground up?

When it comes to approaches, you have tons of options. There is REST, SOAP and XML-RPC, just to name a few. The most popular in today’s APIs is REST. RESTful APIs are simple to use, and the amount of data you send is much smaller when compared to SOAP. You may also want to base your choice on who your audience is. Some people may just love SOAP. Xnigte has 50+ financeAPIs and close to 5 billion+ calls each month. For data format, once again, you have plenty of choices. However, the main one is going to be JSON.

Your API needs to be flexible. What makes an API flexible? It needs to provide choices for data formats, protocols, and the version you want to use. Gives developers control of partial queries, updates, and batch operations. Offer advanced options like web hooks, streaming, and caching.

Something else you’ll want to keep in mind is the time to your first “Hello World”. You want to make it really easy for a developer who is new to your platform to get up and running. There are a few ways you can do that.

1) Make it clear what you do

Take Stripe’s home page for example. You instantly know the problem which the API solves, who it’s aimed at, and what it does.

Stripe API homepage

Stripe homepage

2) Offer a free/ trial period

Get your users hooked, then sink your hooks into their wallets. Make it fast and easy to sign up. Again look at Stripe. It’s so fast you can even skip over the signup process to get going.

Stripe Signup Modal

Stripe Signup Modal

3) Well organized & well written documentation

Your documentation needs to be clear and easy to understand. Provide lots of example code, for as many languages as you can. The more you can people started in the right direction, the better off you are. If you can provide tools to for users to start playing with data, then you are even further along.

4) Manage your API

Your API needs to be managed. Components such as security, key management, monitoring, reporting, scaling, rate limiting, and versioning need to be managed. One other thing great APIs do is measure things like Traffic (total calls, top methods, call chains, quota faults), service status, and support (tickets, response times, community metrics). These things can make or break your application.

5) Provide great support

What makes your API supported? Great developer experience. This starts with the signup and includes everything from guides and references, SDKs, to the pricing. Great support and evangelist teams are active, engaged, listening, responding, and present at events. Your API needs to have a communication channel and a user community in the form of forums, a blog, social media, email support, and an app gallery showcasing the best applications.

Now, you have the tools to build an amazing API. Go build it! 😉