What makes a good API?

by Adrian Hennelly
19 Jan 2016
4 min read
Share this article:
What makes a good API?

Believe it or not we are in the age of the API, no longer should an API be a nice to have or an afterthought. A good API is a massive asset to an application and the business that runs it, an API allows clients to use your application in ways that may not have been intended and this can provide a commercial benefit to both you and your clients.

So what makes a good API? Many things but there are a few key items that usually make or break a good API.

Target Audience

When sitting down to design an API there is one key thing that your team needs to keep focus on, and that is your target audience. Whether you like it or not your API is going to be a product of your application, and like all good products it needs to be targeted at the correct audience. Once a target audience has been determined your team needs to ensure that everything that is built is built in the context of this target audience.

When building your API it’s easy to fall into the trap of having your API reflect an internal class structure, this might seem logical but does it work from the perspective of your target audience? Usually it doesn’t but fixing it doesn’t need to be a lot of work, depending on the size of your application this restructuring of your end points can be easily handled with a simple routing class.


An API lives and dies by its documentation, there are many great APIs that don’t get the use that they could because they are hamstrung by inadequate or out of date documentation. Documentation should always be up to date and publically available as well as being housed online in an easily accessible location.

Here at Adrenalin Media when looking to integrate a client’s application with a third party API the biggest variation in cost isn’t the complexity of the API it’s the clarity of the documentation, a poorly structured API can be saved with great documentation but unfortunately the reverse isn’t true.

An APIs documentation is UX for developers, so when it comes time to test your API take a sample from your Target Audience and give them access to the API and the documentation with no other input and see what they come up with. You will be surprised at how seemingly self-explanatory endpoints can confound.


I don’t know about you but when someone asks me how to tie a tie my usual response is “Here, let me show you.” In the same way a good API needs to have examples, preferably in more than one language.

Good examples should be able to be pasted into a browser or terminal and give the user a response. An example should include the request and an example response so a user knows if what they are getting is correct.

There have been many times when working with an API where I find myself in a situation not knowing if my request is malformed or if the response is supposed just empty because there are no results. The GitHub API has great examples (


Even if your API is small it should be versioned, this allows your team to iterate on the API quickly without having to worry about breaking it for existing users. As a rule of thumb any change in input or output for existing endpoints should result in a new major version.

Opinion is divided on whether an API version should be in the URL or request header ( having it in the URL goes against the concept of hypermedia ( but having it in the URL allows users to explore the API via their browser. This really comes down to who your Target Audience is and providing the best solution for them.


Figuring out how to price your API can be a difficult balance between ease of uptake and return on investment. Building a good API isn’t cheap, and a good business needs to have a plan to recoup these costs. There are 4 main business models that are commonly used by API holders.

Free / Freemium

No upfront or ongoing fees but in the case of freemium the API provider takes a cut of transactions made using the API. This model is currently used by Facebook and the Apple / Android app stores.

Developer Pays

Charge the developer that uses the API a fee, usually subscription based. This is very common with APIs from large online service provides like Amazon Web Services and Google AdWords.

Developer Gets Paid

Usually affiliate or revenue sharing based, the API creator pays the developer for generating income via referrals or views. Amazon uses a referral system for publishers who advertise Amazon products on their sites and Google AdSense uses a revenue sharing model.


The indirect model usually revolves around offering your API to users for free but the functionality of the API will allow users to increase revenue thus allowing them to spend more with you. Ebay does this with its seller management API, by making it easier for sellers to list their products they will list more, resulting in more revenue for Ebay.

For more information on API pricing models check out this great article on GetElastic (

Collect Usage Data

The beauty of APIs is that they allow other development teams to take your product and make it do things that you never considered, as a result it is important to collect as much data as you can on how your API is being used. This data should then be used to justify changes and additions to the API. Without this data you can only speculate on how your clients are using the API, having tangible evidence that can be used to drive a product roadmap allows you to develop your API to best meet the needs of your users.


Whether big or small an API, if done right can be a great asset to any online application. When planning to build an API it is important to keep the above points in mind and have a plan in place before beginning the build.

If you would like to read further on what makes a good API please check out the links below:

Share this article: