Opinion: Three tips for the healthy API

Today’s cloud platforms are changing every part of the software stack: compute, payments, maps, storage, communications. Platforms are making it easier than ever before for developers to test ideas. This is the essence of software, and it’s happening faster than ever.

The significance, therefore, of running a healthy API cannot be overstated. It’s the only way, ultimately, that companies striving for developer adoption and retention will be able to achieve their goals.

But what is a ‘healthy’ API?

Developers, whether employed in large enterprises or simply building in their spare time, share a common desire: they want, and need, easy-to-implement, accessible technology to fuel whatever it is they want to build.

Successful APIs are those built with developers in mind, to provide the agility to innovate and iterate quickly; any other kind is simply not healthy for the business. When making an API, businesses must remember that the developer is the customer.

Here are a few essential tips to consider when creating a ‘healthy’ API:

1. Respect

An abstract enough term, but in the case of the healthy API, respect refers to an appreciation for the time and efforts of the developer.

Organisations should take time to understand the developer’s needs and wants, in order to glean valuable insight into the developer journey and what does and doesn’t work. Hackathons can be a great way to do this.

Example: no maintenance windows! A business can have opening hours, but an API should definitely not. Overpromising on latency can also be a big no-no: if a company expects developers to build on its platform, then it will first need to build trust with them.

But respecting the developer starts with the documents – these should be easy to read and navigate. Including quickstarts that are easily built, as well as user-case samples, can make life much simpler.

Utilising Helper Libraries, or SDKs, can also help developers to write in their preferred language. Any healthy API should be sure that, as developer habits and preferences change, it does too. Doing the research (Stack Overflow’s annual global developer survey is a great start point) can help businesses to help developers.

2. Feedback, feedback, feedback

Once the research has been done, it’s critical to keep receiving and acting upon feedback, often and early, to ensure the API stays useful to the developer.

While an API is in alpha, initial feedback is vitally important for informing massive changes that might have to be made. Going into Beta can certainly be a sign of progress, but any dramatic changes made at this stage can cause a serious headache – an easy way to disrespect the developer’s time and efforts.

3. Simply Powerful

It’s important not to confuse power and complexity. A developer should be able to create something meaningful on a healthy API within ten minutes. Companies should constantly be reviewing the design process to make sure this is possible and, if they can’t, figure out from developers and customers what’s stopping them.

That’s not to say that complexity is unimportant, rather that different problems require different tools, and those that are complex should be opt-in.

What does this mean in practical terms? Take Lego blocks, for example, which start simple and are gradually built into complex structures. Someone looking to build, say, a Lego house can choose to do so in a manner that best suits them – choosing varying degrees of complexity according to their needs. The builder is not required to use an exact amount of blocks or a specific colour or size.

Complexity should scale upward and build on the most simple of API applications. A developer who is new to your API will follow this same logic – using sample applications before gradually adding complexity.

Any builder needs a good toolkit and, when it comes to the developer, providers should aim for their APIs to be in that toolkit. By making the developer experience as seamless and stress-free as possible, they will be far more likely to adopt an API and use it to solve problems.

Ultimately, developers are the gatekeepers to the future of any platform. By following the principles above, companies can be better placed to provide a healthy platform: one which empowers the developer to build the next generation of applications.

Do you have any further tips for a "healthy" API? Share them in the comments.

Related Post

Rojenx is a leading concept artist who work appears in games and publications

Check out his personal gallery here

In other news …