Anatomy of an API
In today’s connected world APIs are part and parcel of our lives. We are constantly invoking APIs, simple activities like posting a status on Facebook or Instagram, sending a text message via WhatsApp, uploading a file to your Google Drive and more involve making a call to an API of some software program running on computing machine located somewhere in the world. APIs have become main street commodity. APIs are everywhere!
I once asked an interview candidate, ‘What is an API?’ to which the candidate’s instant response was — ‘It’s a contract!!’. This is the most succinct definition of an API or an Application Programming Interface.
Dr. Nelu Mihai, in his article, provides a beautiful description of an API — “We all work and use something that is called an API i.e. Application Programming Interfaces. But, what are APIs from a mathematical standpoint? They are invariants, which allow us to access the “micro universe”, they connect us to, always in the same way, i.e. with invariance.”
As complexity and computing requirements of programs evolved the linear execution of logic started to modularize. Today components of highly distributed architectures — like cloud computing — are orchestrated by well-defined application interfaces that enable programmability of these functional components.
Let us now dissect an ideal API and reveal its composition and properties:
Structure
An API has three basic syntactic components:
- An identifier — A named component that uniquely identifies an interface point for an application. A well designed API should have a unique name, within the scope of the application. For example REST interfaces have a uri like structure that is unique in the context of the application.
- A parameter list — A parameter list should be sufficiently encoded for the API to give contextual meaning to each value in the list.
- A return value — One or more return values from the processing of this API. The return value should also encode errors of the API invocation.
Semantics
An API has clear semantics. A well designed API is semantically self-explanatory. It should describe the business function that the interface drives.
Faithfulness
An API faithfully carries out the intended functional behavior. For example if an API is intended to add numbers, it should always add numbers, any other digression is a breach of contract and can lead to unintended consequences.
Fault tolerance
An API is fault tolerant. While this is not a strict condition an API should provide fault tolerance, almost all modern services, specially the “as-a” architectures, are available, thus there is an expectation for API invocations to always be processed.
Concurrency
An API guarantees consistent behavior for concurrent invocations. In a distributed environment concurrent API executions are a norm and the API should guarantee consistent execution of the underlying business function.
Channel agnostic
An API is agnostic to the channel of of invocation.. Whether the API is invoked through browser or REST or command line or a mobile app, it should execute the same business function.
Compatibility
An API once written should run anywhere. This portability allows easy migration of applications and also lends itself to heterogenous architectures. API should be invocable on any platform.
In closing, the world is not an ideal place, and it is not always possible to write ideal APIs. However, I postulate that building APIs that have most of the properties listed above, would result in a rich user experience. I further postulate that designing ideal APIs forces the underlying software to be highly modular, maintainable and scalable. Finally, today’s dense digital ecosystem owes a lot of its existence to great APIs!!
