Blog Image

Personal API Experience

Daily musings

Sharing my day to day lessons, ideas and contemplations of architecting, developing and maintaining services (API) in the global marketplace we call the internet.

The Butterfly Effect

API Posted on Wed, September 05, 2018 21:11:36

We are currently doing some domain driven design to understand our primary business domains and identify the appropriate core APIs required. This is an exciting yet daunting time – some domains look far too simple while others seem overly complex and almost impossible to model. One such domain is the payments domain.

A few weeks ago, during one of the payment domain workshops, one of my colleagues compared payments to a butterfly and challenged me with the question: “How do you model a butterfly?” My knee-jerk reaction was to rise to the challenge and prove it possible, but I soon ran into the problem. Butterflies are the end state of metamorphosis!

The butterfly has four stages to it’s lifecycle; egg, caterpillar, pupa, butterfly. Each stage is different and has a different goal. The challenging part is, while the creature is the same, its life stages are completely different. The egg is simply a sphere with something growing inside. The caterpillar is a long cylindrical creature with a lot of legs. The pupa is a mass of thread woven into a cocoon shape. The butterfly has wings, and six legs. How can the same creature be modeled if it is a completely different object during the stages of it’s life?

This stuck with me for a while as I consciously left it to percolate in the back of my mind. Yesterday, while on my way home on the metro, I had the “Aha” moment!

The answer is you can model a butterfly – by the individual stages of the creature at any moment. The question leads you to assume you need to model all stages of the creature as one model since it is one creature. This you cannot model. The relationship between metamorphosis and the butterfly is the same as payment to transaction. Both are a process, not an entity.

So, simply put, model the stages of the payment process as separate entities and serve these as core domain APIs. Next create process APIs that manage and orchestrate these core domain APIs to fulfil the payment process.

It’s just as important to phrase the question as it is to understand it.

Photo by

“Making coffee” to explain APIs and Domains

API Posted on Wed, September 05, 2018 20:08:17

I was invited to a meeting recently, to explain APIs and why they are important for our digital blueprint. I had no idea who the audience was nor their level of understanding of the basics of APIs. So, with no handy deck prepared for the meeting I entered the room, armed with my laptop full of previous presentations.

I was introduced to the team and the scene was set – “we’ve heard about APIs and need to plan to do them next year”. This prompted the obvious question: “does anyone know what an API is?”. Being an honest audience, the response was “no, but we’ve heard they are reusable and will make our life easier when we have them”.

I first explained the simple stuff; that an API is simply a resource made available to a computer in the same way a website is made available to us humans – via an address. Next came the challenging part; time for coffee.

Making coffee is second nature to us, but imagine trying to get a computer to make you some coffee? You have to tell it explicitly what you need done and the more information we give the computer, the more questions may be raised: What is coffee? How much milk? Do you want milk? What is Milk? Where does milk come from? What is a cow? Where do I put the coffee? What do you do with coffee? These are some of the notions we take for granted as humans, because we’ve learnt about coffee. Now, computers can also learn about coffee, but that is a completely different topic; not one we will cover here. Suffice to say, getting a computer to make coffee requires a lot of attention to detail.

So, how do we do this? Well, we do that same thing we do with most problems; we break them down into smaller pieces. Making coffee involves a number of “things”; water, cup, teaspoon, coffee grains, sugar, milk, kettle, etc. Lets call these domains; the ‘coffee grain’ domain, the ‘cup’ domain, the ‘milk’ domain, and so on. Now, we can take each domain and define the attributes (properties) of it. For example ‘milk’; it’s white in colour, is a liquid, is usually cold. The ‘cup’; it’s a solid, it can hold a certain volume, it can hold liquids, it has a handle. Once we have defined these domains and their properties, we can now tell the computer how to use them to make coffee in simple steps.

  1. Boil water in the kettle
  2. Put one teaspoon of coffee in a cup
  3. Put one teaspoon of sugar into the same cup
  4. When the water in the kettle has boiled, pour 200ml of the water from kettle into the same cup
  5. etc.

APIs can be created in the same way. We define the basic domains of the functionality we want to expose as services (another word for API). In our world, these domains could be customer, account, product, transaction, etc. These form the reusable core APIs. Now, we can use these core APIs to do more complex stuff, like creating a payment API (process API) which orchestrate the core APIs.

  1. Authenticate the customer
  2. Get the customers accounts
  3. Select the right account
  4. Create an instruction to pay the customers registered beneficiary from the selected account
  5. Authorise the payment
  6. View the transaction

With these basic core domain APIs we can now perform multiple other processes. Using most of the domains associated with making coffee, I can replace the ‘coffee grains’ domain with ‘tea bag’ domain and have the computer can make me some tea instead.

Photo by Jessica Lewis from Pexels