How to build a 'good' API

Many parts of the software industry would have us believe that a progressive approach to Application Programming Interfaces (APIs) denotes the mark of a platform's prowess and power -- but what are they... and how do we tell good from bad?

shutterstock 1253901313
Shutterstock

Acting as a sort of ‘gluing gateway' between different pieces of software, the API was first defined in its modern state at the turn of the millennium. But what are they, really, why do they exist and how do we know if we're working with a good one or a bad one?

APIs defined (formally &informally)

Formally, an API (Application Programming Interface) is the contract between two pieces of software that need to communicate. It defines the language used and the expected results and responses such that one system can hand-off a task to another system.

In the world of cloud software, API generally refers to communication between systems that happens over the internet. The same protocols, HTTP and HTTPS, used by web pages in your browser are used by software systems to communicate with each other. Most modern applications are a combination of custom-built in-house code, open source code and APIs into other, third party, systems.

Cloud software will often provide a user interface as well as a programming interface to allow both types of interaction. So someone can add events to their calendar but also allow other approved software systems to add events when, for example, a booking is made.

If we accept that APIs now form a relatively indispensable part of the composable componentised world of the interconnected web and cloud, then how do we know if we're using a good one and what characteristics mark out a gourmet first-class API?

To continue reading this article register now