There is a simple concept that’s been around long enough as fallen behind in our most basic programmer-memory, something that is too common to be worth discussing about and sometimes so uncanny to us, that even in front of our very eyes we regard it Tautology.

APIs everywhere

Of course, as it couldn’t be other way our mysterious guest is API. The term stands for Application Programming Interface and it refers to:

If we had to use Jargon to define an API we’d say: Everything is an API. This, seen shallowly, provides no useful information about what APIs stand for, but we all know nothing in this life appears with its reckoning-day dress, a subtle eternal truth lies beneath every concept and is our duty to unveil such an insights.

A little bit of Context

The idea may have come out of the blue so let’s place down a context so we can land it to concrete grounds.

A while ago I participated in a project that turned out to be an integration with a Microsoft Power BI based platform. The problem might have been described, from a high level perspective, as a big Domain Model that required a profound and thorough analysis, hence a complex design for building a proper Solution to that problem.

To sum up and prevent myself drifting too much about the Domain it self, the idea was to import a series of data into an E-commerce platform(let’s call it Axis) based on specific business rules and perform a series of interpreters in order to bring it down to current platform’s policies. Those data would travel across from BI to Axis going through a series of processes dictated by Domain Policies, once in Axis then a series of other Axis specific policies must had been done so the Business necessities would be met.

                   Data flow
                                                     
BI   --------->    Middleware   ------>      Axis  
 
                      Domain              Interactors
               Constraints/Policies       Persisters
                                          Presenters
                                             ...

So basically, and without entering into IS details like components, interactions, or processes diagrams, the Software to design was pretty much like in the picture, a middleware that reads interprets and transforms, according to business rules, data coming from BI platform and place it into Axis based upon its constraints, then its components come into play in order to present it to consumer interfaces and processes.

Valid to point out that Domain Policies are transversal to any of the components/actors/agencies drawn up in this made up high level diagram.

API is a Developer’s best Friend.

As you, reader, might guess this foresees a lot of pieces to gear up for the sake of the desired solution. So the concept comes stronger.

What if i treat every one of those pieces as an independent unit that is testable, scalable and deploy-able regardless its surrounding universe? This is where API finds its highest purpose.

Normally, an application is built upon a specific Framework without even knowing that a Framework is an interpreter from Base Language to higher level language, in this case your API. The Framework absorbs your Domain in a way that it reduces it to a set of snippets spread all over its layout where you, developer, lose the connection between the Framework and your API(your Domain).

This is why is essential to tear down a Framework-Centric mindset and start thinking in terms of APIs. Your Domain grows up a sort of special Language called by many, especially in D.D.D circles, Domain Specific Language(DSL from now on) . In our Study Case the rule as follows:

Axis is an interpreter from language T to language P.

Where T represents our DSL and P is the language Axis is built on top of. But the fact is that there must be an interpreter between Axis and T that allows us to migrate our solution, if needed, to another interpreter so the Domain modeling remains untouched.

A high level Solution brushstroke(to our example)

So we, the team, end up building an DSL to our Domain, then the Domain boundaries that settle up the frontiers among different APIs and, from there we started to build the proper interpreters to each API. All independent from Axis.

Finally we created the ports and adapters to Axis, again as APIs and wrapped every up.

Every single component/API is independent from the rest and the only thing that interconnects them is the service contract dictated by Domain Model and defined in the bounded context in the flesh of an Interface.

If we had to come down to specific technical details: we have a set of Interfaces that define every Domain Use Case and their corresponding interpreters/adapters that satisfy the policies of such a Use Cases.

This is great because we were able to implement and test(not independent deployment since P is interpreted language) every API without concerning about the rest except for the fact that the Interconnection must be respected, but this is what the service contract is for. A simple(not single) set of scenarios and tests were sufficient for sealing that up.

Some of the Domain components resulting of this were: Reader, Interpreter, Transformer, Persister; they all played their role in the Drama being developed and at the same time were an isolated microcosms with self-contained life.

Epilogue

The better way to come to grips of what a term represents is, sometimes, extrapolate it to a real life example, to establish a simile that allows us to deconstruct what’s behind it and bring down the myth created out of, very often, preconceptions and assumed ideas of something.

In our case, the term API it’s been long enough to just make us assume an API is a Web Service exposition, even being true it’s just a subgroup, but the reality is that is way more than that, is the foundations of all systems. It allows us to encapsulate core specific details and provide a mean for visibility to system’s consumers. It is true that the need of an API oriented design is more evident when dealing with complex and rich Domains modelling, i wouldn’t come up with an API based solution when developing my aunt’s flowers store of course, everything on its fair measurement.

I hope this post have claimed your attention and I’m looking forward to having a feedback.