The Anatomy of Integration Part 1 - Services & APIs
Written by Jonathan White
Published 23 February, 2021
Services. Microservices. Web Services. APIs. Interfaces. Contracts. SOA. Navigating the cornucopia of integration buzzwords can be a challenge, one made ever more difficult because of the inconsistent and interchangeable use of these and related (but not duplicate) terms in tech blogs and articles by people and companies who really Should Know Better.
But does it really matter?
As long as we know what we're talking about, is it so bad that we use the term API and Service interchangeably?
Is it such a terrible thing that what we call a Microservice to keep the CIO happy and convinced we're riding the new wave of hype is really just a lightweight independently deployable Web Service?
In a word, yes. Ambiguity is difficult to support. It leaves us open to the danger that if we're not designing and implementing what we say we are, then we will not realise the promised benefits of whatever it is we say we are implementing. This displeases business owners and c-level executives everywhere.
There are too many buzzwords to identify and compare in a single blog, so here we will look at two commonly conflated topics - that of the Service and the API. How do these two concepts overlap, and how do they differ? Subsequent blogs will explore how you're almost certainly not doing Microservices (at least, not quite) and the fact that there are various other flavours of Service Oriented Integration, and how the bleeding edge isn't always the sharpest.
What is an API?
Now, we all should know what the acronym stands for; Application Programming Interface. But it's one of those acronyms that rolls off the tongue with little thought being given to the meaning behind it. So what is it, really?
The key letters in the API acronym are the A and the I. The P is a bit of a throwaway filler, because everyone loves a TLA, and if we remove it, we would be left with "AI", which has already been claimed as a fairly significant concept in computer science.
A is for application
An application is a bit of a catch-all term for an amorphous "something that does something." In Service Oriented Integration, the application almost certainly refers to the service itself (more on what that is later), but outside SOI it could be any lump of software that needs to interact with something outside itself.
I is for interface
Simply, interfaces allow one thing to interact with another in a controlled and predictable way. Keyboards, mice and monitors allow us to interact with our computer. Pages of a book allow information to interact with our minds. Cars have many interfaces to abstract us away from the complicated inner workings which are kept quite literally "under the hood". In SOI, APIs are a way of exposing a service's functionality for use by external parties.
All good interfaces are defined by a specification or contract. This tells the user of the interface what functionality the API provides and what it requires from the user in order to provide it. The contract can also outline the non-functional requirements of the user, such as how regularly they can call the API and what security information they need provide when they do so. The most common API specifications in use today are WSDLs (for ye olde APIs), OAS (Swagger), and RAML (For ye MuleSoft APIs). New standards such as async API and others continue to emerge.
When I first began my rewarding journey into Service Oriented Integration, SOAP was all the rage. Imagine! Being able to define an API contract in less than a year using a language which made you look really smart, primarily because no-one could understand it.
After a while, it became clear that the only people who really liked to write WSDLs were masochist and sadists. XML became awkward and terms like "venetian blind schema design" sent sane people scurrying to the hills. A lighter, hipper cousin was emerging in the form of JSON. Around the same time, REST was being explored as an architectural approach to expose access to an application's resources. Unfortunately, some people conflated these two emerging concepts, proliferating the simply wrong opinion that a REST API is just JSON over HTTP.
Now that REST APIs are entering their twilight years (although I expect it to be quite a long twilight, the sort Iceland experiences in mid-summer), exciting new standards and patterns are stepping up to take their place. GraphQL allows the user to request just the data they are interested in, in the format they want, instead of being victim to the service dictating the structure to them. Event streaming reduces the dependencies between the applications further by providing a stream of events which interested applications can asynchronously subscribe to instead of requesting the data on-demand.
A service (from the perspective of Service Oriented Integration; there are other flavours of services out there) is a self-contained thing that performs a task (provides a service). The task that the service does depends on how it was designed and decomposed. Microservices and Domain Driven Design model services on the functionality of the underlying business. Service Oriented Architecture often layers different services on top of existing IT assets. Regardless of how they were designed, at its heart a service is a discrete "unit of functionality" that can be accessed remotely.
Services and APIs go hand in hand like a leg and foot. That's a terrible analogy. Services require APIs in order to be accessed remotely. APIs require something behind them to fulfil the operations or provide the data that they expose. The API is actually part of the service, it's the part that handles the remote request, applies policies to protect the service, and passes the relevant request information down into the deeper layers of the service for fulfilment, and then handles the reply to the calling system. Beyond the API, the service also includes the implementation (code) which applies domain logic, accesses data, or calls other services in order to fulfil its function.
Think again of a car as a service, with myself as a remote application. The services (cars) function is to move my lazy behind from point A to point B, preferably stopping off for a responsible beverage at a pub somewhere between the two. The car's API would be the steering wheel, gas, brake and clutch pedals through which I interface with the car. We consider these parts of the car, the same way we consider an API as part of a service. A steering wheel alone will not do me many favours, and a car without one is just plain dangerous.
If you’d like to know more about our work with any customer, please contact us here: