API vs. Service - Terminology Matters

Those who know me or worked with me know that, in technical context, I am a stickler for accurate terminology and non-ambiguous usage of words. I owe it to my high school algebra teacher who tried valiantly to teach us (a group of 11 grader geeks in Alborz high school in mid 80s)  Field Theory. As it is the classic methodology, he would spend so much time on setting up the problem, introducing terms, definitions, axioms, propositions, properties, lemma ..that by the time he got to the main theorem, he had lost most of us. When we objected, he would say

If your words don't have accurate meanings, you sentences are ambiguous, when you utter ambiguous sentences, your arguments are confusing and when arguments are confusing, you start a war. 

We were way too young to understand the wisdom in these words then, but I am a believer now.

In the past few years, I have seen very frequently the two terms API and Service used interchangeably. They are not the same! Granted, there is no official definition but I would like to offer one that helps in all discussions regarding both APIs and Services.

Service is a software component, one with well defined contract and boundaries (both code and data), services are build by Service Providers (or Producer). Service orientation is a style of architecture for building distributed systems.

API on the other hand, describes consumers view of the world. API is what is exposed to consumers and determine the programming model by which consumers interact with producers.

Services are often exposed as APIs.  APIs MAY (or may not) be implemented by a service. Figure below illustrates this concept:

API endpoints are denoted by eN. In this picture, API e1 is an aggregation of three operations each belonging to a service. API e2 on the other hand is a simple delegation (or routing) to one operation of Service 1 (S1.O1)

This picture defines what API and a Service is clearly and allows us to separate consumer concerns from producers concerns, for example API consumer (and API type space) may include a definition of a User that includes a unique identifier, email, a brand name and a reputation indicator. Consumers expect an endpoint to supply this type - they call this endpoint an API - however no sane domain model would encapsulate and implement the notions of Identity, Branding and Reputation in one service. The User API end point aggregate (and transform) the output of the three services, but more importantly allows producers to build services with right boundary and granularity independent of how they need to be consumed.

As the last point, I have to emphasis that our STRONG preferences is to keep the API intermediation layer "dumb" and simple, actually we often encourage simple delegation, and rarely aggregate or transform outputs and almost never do anything remotely resembling business process orchestration or anything involving business logic (aggregation and transformation are strict mathematical operations not business logic). All API ecosystems need to have an intermediation layer, but it has to be kept as dumb as possible (but not dumber).

Now that I defined APIs and Services, in my next post, I will focus on Portfolio of Service - a collection of coherent services that power APIs (usually at a scope of a company or large domain). I specifically list the lessons we learned from designing, implementing and operating CommerceOS.