Making Coffee - to explain APIs and Domains

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. Let's 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 the 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.

Craig Hughes

Photo by Jessica Lewis from Pexels