Unravelling the Differences Between Services and APIs
Drowning in terminology
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
F is for friends who do stuff together
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 to the user, such as how regularly they can call the API and what security information they need to provide when they do so. Some of the most common API specifications in use today include WSDLs (for ye olde APIs), OAS (Swagger), and RAML. New standards such as async API and others continue to emerge.
Evolution of the SOI API
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 idea 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 might experience 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 API 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.
What is a service?
A service (from the perspective of Service Oriented Integration; keep in mind 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 provides depends on how it was designed and decomposed. Microservices and Domain Driven Design model services on the capability 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 may be accessed remotely.
How the twain shall meet
Services and APIs go hand in hand like a leg and foot. That’s a terrible analogy. Services require APIs to allow remote access. Correspondingly, 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. Remember, an API doesn’t necessarily mean REST, JSON or even HTTP; it is any defined entry point into a service for access by a third party. 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 function of the service (car) 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.
To conclude
So, here endeth the lesson. APIs are not Services in the same way an ATM is not a bank. We can start using this in our every-day integration vernacular. No more buzzword sins or false equivalence. No, you aren’t going to write an API to amalgamate data from system A and system B. That would be a service. However, you might then provide and manage access to this service by including an API for other applications and users to access the amalgamated data. Services do things and, as part of the service, APIs make sure that the thing the service does is available to those who might want to do it.