Join For Free

Designing an API the Right Way Posted 1 year ago

Everyone and their dog’s are building API’s 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 dev’s on the project mentioning that we should have an API. At the time I thought he was crazy. We hadn’t even launched the product so why would anyone want to use our API, let alone our App. Our app eventually failed, mostly to 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? API’s 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 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 your self when designing you API are, what are the goals or goal of this API and who will be using this API? You need to start asking yourself questions like what protocols and data formats are you going to us. How are you going to lock down your app? Open source framework or build it from the ground up? 

When it comes to approaches you have tons of options. You have 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 commpared to SOAP. You also may 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 you again have tons of choices but the main one again is going to be JSON.

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

Something else you’ll want to keep in mind is what your Time to first “Hello World” is. You want to make it really easy for a developer who’s new to your platform to get up and running. There are a few way you can do that. Make it clear what you do.  Take Stripe’s home page for example.

You instantly know what the kind of problem the API solves, who it’s aimed at and what it does.  You also will want to offer a free or trail 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. You need well organized and well written docs. They need to be clear and easy to understand. You are also going to want to have lots of examples of 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 a user to start playing with data then your even further along.

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

Your going to want to provide great support. What makes your API supported? Great developer experience. This starts with the signup and includes everything from guides, to references, SDKs, to the pricing. Great support and evangelism teams that are active, engaged, listening, responding, and are at events. Your API needs to have communication and community in the forms of forums, a blog, social media, email support, and have an app gallery show casing the best.

Now you have the tools to build an amazing API go build it and add it to Mashape. ;-)