YourAPIExpert Essential Series

Armed with our basic knowledge of API terminology from this article we turn our attention to the basic make-up of an API’s internals.  In this article we take a look at the DNA of an API.

This article is part of the  ‘Essentials’ series and focuses on the ground-level understanding required to undertake the journey in to the world of APIs and will through the course of the series build upon your skills and introduce you to core concepts.  This series is intended for people who wish to gain a rudimentary understanding of APIs such as students, new software developers and managers wishing to gain understanding and experience within their team.

Although we understand what an API is we now ask ourselves what an API does.  In a previous article we discussed than an API is, in essence, a mechanism that exposes an individual or collection of pre-programmed functions in a manner that supports safe and predictable execution.  For any piece of code the ability for the operation to be safe and predictable is the holy grail of development.  Predictable operations means that the code executes the same way at each invocation without variance as variances between expected behavior and actual behavior usually indicate a ‘software bug’ often difficult to isolate or understand.

In terms of software development APIs have many synonymous names depending on their context.  For example when working on applications in PHP or Python where a framework or library might be in use one might hear of using ‘hooks’ and whilst working in C, C++ or even Java one might hear of the concept of ‘bindings’ for the same thing.  Other languages have other descriptions but in essence they all refer to a programmatic way to access an ‘interface’.  It is this interface which exposes specific functions and functionality which an application can interact with.

These concepts carry forward to those APIs used on the world wide web and here I will use terminology derived from many years of experience and from working on sophisticated API management platforms.  Irrespective of what the latest marketing buzzwords are for this basic terminology the construction of the API remains static and you should be able to substitute and understand these terms with ease over time.

In all but the most specialized of cases an API (any API) bridges a gap between two disparate applications and just like a bridge it has two ends to it.  On the one end, which we will term the ‘Southbound interface’  is the functionality that you wish to access and on the other end, which we will term the ‘Northbound interface’, is the functionality that you wish to expose.  This is a slightly tricky concept to understand so let us paint the picture with a hypothetical example.

In the image to the left I’ve drawn up a rudimentary process flow of an incoming order from an on-line store or web interface.  At several stages through the process the order is stored and updated in a database and similarly there are several stages of interaction with third-party payment providers and back-end systems.

To understand the differences between Southbound and Northbound interfaces I will transpose the critical elements of this process flow on to the API’s DNA.

Using our process flow above this image on the left separates our bridge (API) in to two logical ends.  On the Northbound interface we can begin to understand that this interface is called upon (invoked) whenever a customer places an order via a mobile application or our own web site.

On the Southbound interface we understand this to be the interface that is used to make calls or invoke functionalities provided by other systems or third-party providers.

To understand how an API functions as a bridge we will expand further on the Southbound interface.  Here we can see existing web APIs for payment (PayPal) and shipping (DHL) as well as disparate back-end operations for order management (SAP), customer communication (email) and data storage (DB).

Paying for items is distinctly different than shipping them and similarly an email is not the same as a payment and therefore the API must be able to accommodate these technologies.  This opens our understanding to the distinct roles of interfaces — the ability to manage and interact with disparate systems and technologies.  Apple Iphone (mostly coded in Objective C) and Android (mostly coded in Java) devices operate on different operating systems and different programming languages and yet with the help of APIs and some standards communicate seamlessly via each other on Facebook.  Therefore one of the core strengths of an interface is its ability to handle systems of disparate types and technologies.

Up Next:  Holding Things Together

Pages: 1 2

Written by YourAPIExpert