Most of us think we know what an API is but cannot seem to agree on what an API should be

The general consensus amongst API providers is that we should build reusable APIs, but consumers want more - they want an API that gives them everything they need. These tactics challenge one another.

Building for the consumer

Consumers of data or functionality want everything in one single and simple package. Facilitating this approach can lead to a plethora of bespoke interfaces each fulfilling only one single user’s requirement. Prospect consumers will find it hard to find the “right” API and, due to the precedent set, may ask the API producer to create a new interface for them.

Building for reuse

On the contrary, if an API is too generic then the API consumer will feel that they have too much work to do. These consumers will have to use composition and/or orchestration on these generic APIs to get the level of functionality they need. Issues of performance and the need to understand the underlying business may become strong arguments for the consumer.

How do we address these two divergent methodologies?

My wife and I do not work in the same industry - she does people and I do technology. I often write as if I was explaining the topic at hand to her, but for some reason, this topic has me flummoxed. I’m struggling to explain this one to my wife in terms she can understand. So, please bear with me, and let me know in your feedback or comments on how to simplify the following descriptions.

Domain Driven Design (DDD) allows us to break business domains into smaller objects called domain entities or value objects – this concept is briefly explained in my previous post on Making Coffee. In banking, we have a number of business domains: customer, account, product, etc. Customer, in turn, can be represented as a number of domain entities including core information, addresses, contact information, etc. The same applies to the other business domains. Domain entities can be exposed as our most reusable API. We call these APIs core or domain APIs.

However, business practices are not only about managing domain entities, we also need to be able to use and or manipulate them to fulfill some business process. To facilitate this, we can compose or orchestrate core APIs to perform a defined function, which we expose as a reusable interface (payments are a good example, see my previous post on The Butterfly Effect). We call these process or composite APIs.

Finally, we have the user interaction channels. This is where the most specific APIs are usually required by consumers and where it is ok to have bespoke APIs for a defined purpose. As long as these APIs are composed of core or process APIs and do not go directly to our core systems. We call these presentation or experience APIs.

Essentially, we create a layered API Architecture. Core API, the building blocks, form the foundation and are predominantly data-driven APIs. Process APIs offer the reusable business functionality by manipulating the core API for a defined process. Finally, experience APIs offer custom user interaction by orchestrating or composing core and/or process APIs for a specific user interaction.

Now, I admit this is overly simplistic and does not cover the performance argument. That can perhaps be addressed by an event-driven architecture which publishes core domain entities (see the Hollywood Principle) and implementing the CQRS (Command Query Responsibility Segregation) pattern. Perhaps the topic for a future discussion.

Craig Hughes

Image from Pexels.com