Building an API: A guide to best practices

August 23, 2017

Building an Application Programming Interface (API) is an important step towards scalability in a tech product’s life cycle. An API allows other programs to interface with your code, bringing about new opportunities for other businesses to integrate with your own through code.

By building an API, organisations can leverage other businesses to connect into their given product, creating synergies and galvanising the tech product as a true platform upon which other businesses can be built. It has been said that Facebook and Twitter were only truly established as platforms when other businesses could leverage themselves on the platform using their APIs. It’s what separated eBay from Craigslist, or Amazon from any other e-commerce site out there.

However, in the tech world APIs can be fraught with danger. There are many horror stories in this world of development, where businesses spend millions on creating something nobody will use, or give their client base an unscalable product. To avoid these, here are some best practices to use in building out your API.

1. Don’t delay development with a business case

Almost always, when building a scalable solution as an API, commercial justification in the early days can be tough. There aren’t a lot of clear revenue benefits, and if the business needs to justify building an API with a business case, it probably doesn’t need one. If the board and CEO have instinctively stated they need an API, this should be done with a lean scope and rough timeline. These things take time, and it can be very hard to know what is needed until way down the line.

2. Be consistent with your ‘failures’

When building something as difficult as an API, use every iteration as a learning opportunity. If the business manages to build the right development platform from the start, chances are that you’re probably heading down the wrong path. APIs need failures to be refined, evolve expanded on. In order to be refined, they almost always need lessons to be learned from. These learning opportunities need to happen consistently through every iteration, so be consistent with mistakes to generate the right lessons to be built upon in the future.

3. APIs are used in every way the user wants, not the way you want

If a customer says they intend to use your API for a use case that doesn’t fit your original bill, just run with it. Unless it is detrimental to your business, an API is a canvas for others to build upon. A canvas doesn’t get to say what art is built upon it, but it simply grants the opportunity for art to be made. By seeing things outside the box, through the eyes of the user, you can see your product being used to a greater extent than you first thought.

4. This is not a revenue opportunity, but a growth opportunity

Finally, it is important to recognise that an API will quite often result in another business being able to derive revenue apart from yours. Don’t take this personally. It isn’t lost revenue for your business a lot of the time (think Farmville on Facebook), but rather a way for you to cement your business in the marketplace.

If your business is ready to scale out, and welcome the prospect of other businesses being able to interface with your code, an API may be the best thing for you to do. By taking it on as a growth opportunity, learning from failure and not setting a guideline with a business case, the business may be able to welcome the weird and wonderful ways other businesses may interface with yours.

businesswoman interviewing male job candidate meeting room
By Annabelle Gonzalez May 26, 2025
Want to stand out in interviews? It’s all about how you tell your story. In this article, Annabelle shares simple tips to make your answers clear, confident, and authentic.
A man and a woman are shaking hands during a job interview.
By Brett Dickinson May 21, 2025
Boost your interview success and impress hiring managers by avoiding these 10 common job interview mistakes that can hurt your chances of getting hired.
A man is sitting at a table using a laptop computer.
By Luke Cranswick May 20, 2025
In 2025, creativity alone won’t cut it - discover why hiring analytical thinkers in marketing is the key to unlocking smarter strategies and serious ROI.
More Posts