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?
Good APIs are invisible APIs
The core truth with APIs is: if users are aware of their existence, then your system (and your programmers) are probably doing something wrong i.e. they are supposed to work seamlessly in the background and never form part of some system error that bubbles up to the user interface layer.
This defining precept is the opinion of Adam Bird in his role as CEO and founder of Cronofy, a company that has been building and commercialising APIs for calendar scheduling applications since 2014. Cronofy is now working to host CalConnect meetings, where global players from Apple to Oath design the future of ‘calendar interoperability' - yes, that's really a technology subdiscipline these days. So as we now interconnect with APIs, where should we actually make contact?
"We think of our service as a stack of entry points. The higher up the stack you go the less you have to do -- but you sacrifice elements of control. The lower you go, the more control but the more you have to build to coordinate," said Bird.
In Cronofy's case, at the bottom of this stack are API end-points to allow interaction with end user calendars to examine events free/busy status and create new events. The next level provides scheduling capabilities. Above that is a fully customisable, embeddable user interface.
Bird explains that any product that brokers access to third party services like calendars or payment providers will have to deal with failure. The goal is to deal with as many of these failures as quietly as possible and raise exceptions when you need to. That means reliability is a key issue, so there's something of a trade-off between complexity (which gives power) and simplicity (which enables API readability and connectivity).
"One technique to ease this is making API calls asynchronous i.e. not able to work in parallel concurrency. That means the software will accept the request to create an ‘event' that won't be completed straight away. If a new workflow needs to be triggered after a given event has been completed, then a new API call is needed. A bit more complicated to implement but a hundred times more robust," said Cronofy's Bird.
Know your (API rate) limits
Rate limiting API requests is important from the point of view of protecting an organisation's infrastructure from runaway usage. It also trains customers (i.e. other organisation's developers making calls to your API) to use more efficient interaction patterns. Firms will need to absolutely establish rate limits from the start and return an appropriate API response when it happens -- in the case of HTTP this is a 429-status code.
In the world of APIs, it's important not to reinvent the wheel. Bird advises humility and says that, generally speaking, API standards have probably been developed by far more intelligent and experienced people than you and your team. So companies should use them where possible. Large companies have invested heavily in API design and testing. The advice here is to borrow, copy and take inspiration where you can.
"Use the language and nomenclature of other APIs. In the early days of our calendar API many of your customers had been using the Google Calendar API so we adopted some of the terminology to make it easier for these new customers to understand what was going on," said Bird.
The hierarchy of API happiness,
Borrowing again from Cronofy's API experiences, it appears that best practice procedures include full recording of all API interactions. This helps third parties connecting to an API to track errors they may not have captured in their own logging. Also key is documentation, which should be considered a ‘shippable part' of any API. People can't use your API unless they can read how. Investing in libraries for popular languages and frameworks is an optimisation on top of this.
"If you have to choose, choose documentation ahead of building a Software Development Kit (SDK). Especially if that SDK is in a language or your team has no experience of. In a hierarchy of API happiness, documentation is the foundation upon which everything else is built. With it anyone can make use of your API, even if there isn't a library for the favoured development language," said Bird.
Finally here, the buck stops at pricing, even with APIs. With pricing, Bird and team say it's important to ensure organisations aren't incentivising product teams against properly embedding an API service. "An approach used by many API businesses is to bill on API transactions. Easy to comprehend -- but can you be sure that this maps accurately to the value of the transaction that you're supporting," he asks.
APIs are everywhere, but there are good, bad and presumably quite ugly APIs too. Knowing where to stand will be the critical choice that determines whether we end up in the gunfight or the saloon.
