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 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
. 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 for 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 fulfil 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 direct 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
) and implementing the CQRS (Command Query Responsibility
Segregation) pattern. Perhaps the topic for a future discussion.

Craig Hughes

Image from