A few weeks back, on a lazy Sunday afternoon, I find myself saying to my girlfriend;
“get your coat… we’re heading to the car!
Because either we get to taste the best coffee in the world or uncover a lie that has been
running for way too long.”
And whichever it will be, it will be great!
To back track how we got here I need to tell you a bit about espresso coffee and my journey
with these beans and machines.
I met a lot of people in the online community, through forums and sites like Reddit, who kept
describing their espresso shots tasting like:
While mine tasted like
Cardboard, Rubber, Skunk, Petroleum and the general taste of Band-aid
See the difference ?
Some years ago I bought an espresso machine; at the time I didn’t do much research. With
limited budget I settled on a refurbished QUICKMILL machine. Mainly because it’s easy to
repair when things to wrong. And settled on a brand of Italian roast beans & a way to make
Now a few months back my coffee started tasting really awful; remember Cardboard, Rubber
& Band-Aid-Like taste.
Now given how prominent the machine is, jumped to the conclusion that there must be
something wrong with the equipment. GEEK
POURING OVER THE thousands and thousands of pages discussing machines I also
bumped into people DECONSTRUCTING and DEBUGGING their espresso shots!
AND THEY DO so using bottomless or naked portafilters. If you search on YouTube you can
find endless shots like this.
And they all seem to unite under the hash-flag #BeansOverMachines
Which is interesting, because if you look at most espresso set-ups, the beans are usually
somewhere off to the site. It’s the machine that gets to shine and bathe in the glory.
Which let me the question we tried to answer on that Sunday - is the ‘blueberry bomb’ a
conspiracy or am I missing something?
basically, the question I’m asking myself is - is this good coffee?
How do you go about and answer such a question?
In part it’s personal, and on the other hand you need to understand the variables that go into
making coffee as well, because there is an objective element as well.
It slowly dawned on me that I was on the peak of mount stupid.
In a massive outbreak of Dunning & Kruger. I knew absolutely nothing.
For those who don’t know DK - is a cognitive bias wherein people of low ability have illusory
superiority, mistakenly assessing their cognitive ability as greater than it is.
Basically, you know so little about something that you are incapable of seeing what you don’t
know. And as a result of that, you overestimate your ability and are overconfident.
I found myself on another graph as well.
This is the Design Squiggle, and it’s used to show the feeling of discomfort, unknowns and
uncertainties at the beginning of a project. It tells us this feeling is normal and that it will be
ok. It’s good to feel like this in the beginning.
And this happens to be also the graph we use at work where we go about and help teams in
their question “Is this a Good API"?
hello, we are Ernst & Flavia, and we work in the API Design & Governance team at ING
Like I said ING is a bank - it’s quite a large company with worldwide present. And we work
with many different teams from many different departments –
teams from mortgage
and most of the time we have teams coming to us with a very basic question: "Is this a Good
Our answers to the question "Is this a Good API”? have been mostly Yes, No, Maybe - and
an occasional “I don’t know”
And we still stand by those answers. Keep in mind that we are no experts in Mortgages,
Savings, Lending, Securities, Accounting, Fraud detection
And though our answers haven't changed, the questions we ask to make this evaluation have
shifted. It is this shift, we'd like to talk about.
In order for you to appreciate this shift, we first have to take you back to where we started.
4 years back when kick-started this whole API thing. My manager created a new API Community and called his friends and bosses to the first
API Community meeting. I had just joined ING, it was my first week. He started off strong showing why ING should move toward an API based
architecture, the advantages of decoupling the front end and the back end, etc etc. But as the meeting progressed, there was skepticism,
bordering on cynicism. During the meeting, there was this huge discussion about APIs versus Webservices. After all, our current architecture
was webservices based. I saw the audience sinking into the mindset - they are essentially the same. So why change.
At this point, it seemed like this was going to be the last API Community meeting. I was at this job for only 1 week now, so thought I'd shut up.
But I couldn't. I saw APIs differently, and hence gathered all the courage I could to make the statement - APIs are designed outside-in.
I still remember the moment, the room went silent. It felt like forever before words came back. Then one guy said - what's outside-in.
I was prepared for that question. Then came a big description about designing APIs from the perspective of the users, the developers using the
API. As compared to inside out.
This took that meeting on a different trail. Some moments later, I found myself using the word Customer Journeys. I should have shut up.
The same guy said, O yeah, we made those for this project we're doing. I happened to know that project, and I said - great, can I see them?
This was it, he got it. Customer Journeys were not a business only artifact. They were a great way to come to an API design. He promised me
to give me the Customer Journeys so that I can design beautiful APIs. We had begun our API journey.
and a 3rd - HYPERMEDIA, and after that other people started talking as well. And the ball
started rolling - we where creating APIs.
And just like the number of API community meetings where growing, so did the number of
We had two starting points - REST & OUTSIDE-IN. Only they weren’t defined that much. But
of course this stopped nobody!
The teams did not have enough support to build and release APIs smoothly. Our
infrastructure and delivery process was not well suited to host all those APIs. Everybody was
doing growth-hacking and shadow IT.
We had to make the process of creating APIs smoother. We needed a Security Gateway, a
Load Balancer, a Continuous Delivery pipeline that are API friendly.
Firstly we needed an API portal to showcase our proud possessions.
Soon I found myself in a new role - a Product Owner. This was “making time”.
I learnt so much being a PO. Nothing I had done before. I had stakeholders, customers, a
team. It was like running a small company. Every two weeks we churned out pieces of
functionality. It was an awesome awesome time.
We called ourselves - Team Origins. We started build our API Platform - The friendly portal
where people could read about APIs, search for them and get assistance on how to build
We gave this portal a cool name - Lonely Planet. It felt a bit that way in the API city if you
were new to it.
And because we where the guardians of the portal, we saw each and every API.
Teams came to us, and asked us to evaluate their APIs and their work. We got e-mail
requesting ‘approval’ and ‘compliancy checks’.
Teams were asking for STAMPS
so naturally we became the stamping department.
We soon noticed that REST itself was a difficult one. You can build very different APIs
following REST. REST itself was not enough. When we looked at our API landscape, they all
looked different, yet, they all followed REST.
It soon became clear we needed guidelines
consistency in naming, structuring of requests and responses, patterns like sorting, filtering,
So we wrote a lot of technical guidelines. Like you have seen several others do as well.
There, REST is solved.
Once we had the guidelines, we could ask more objective questions and noticed patterns
and other commonalities between APIs in our landscape. We documented these, and they
formed a layer above our guidelines.
People started using the /me as an identifier for the user, to hide privacy sensitive numbers
such as IBAN bankaccount or social security numbers.
Also use-cases for URL encryption came up in the form of an Encrypted GET or performing a
We started using Richardson Maturity Model to rate and nudge APIs to shift up towards level
Level 3 APIs guide the users of the API by giving possible state transitions in the form of
One discussion we kept having was one regarding which technology to choose for the implementation. Which
tarnished the discussion on the interface design.
You have to understand that up until now, the portal where we registered APIs did so by accepting a
Name, Description,Team contact details , And the motivation for the API ,And a link to the documentation the
So when we tried to answer the question; “Is this a good API?” We ran into a lot of discussions along the
Our API uses the best tech, we use Scala and Cassandra. Or we are just a backend team making a service
to access our database, we don’t know what our users want. We are here just to support the mobile app, or
We felt it was high time to separate the implementation from the interface. Also every team documented their
API in a different (and often incomplete) way. Therefore the current version of our developer portal accepts
OpenAPI specifications as the starting point. Which is leading to a whole new problem, which we’ll get to in a
Separating the interface from the implementation and having a uniform way of documenting
and collecting our APIs allowed us to see the entire landscape.
And what did we see? We saw that people created APIs from different perspectives.
We gave names to these design perspectives - because it turns out that you can create the
same API in vastly different ways.
Self – where you create an API from the perspective of your internal processes, databases
Screen – where your API follows the screens of the application it supports
Stage – where your API lets go of both Self and the Screen, and allows for multiple
interactions to happen.
In our support to teams, we encourage them to make this a conscious decision, because we
observe that, if this choice is not made consciously, you end up with what you know best and
start designing from the ‘self’ perspective.
It is important to remember that up until now, most of our APIs where created for internal
usage - either between teams or to support apps. Some were for partners and we had some
other things on the side, but we didn’t have any true public APIs yet.
than the best thing ever happened - regulation!
PSD2 - 3 APIs to be compliant (AIS, PIS, CAF)
All the effort and infra to deliver these mandatory APIs. So why stop there?
Suddenly APIs are the hype! The buzz-word that a lot of people didn’t really understand. We
saw the influx of non-engineers into our trainings who wanted to understand APIs.
There are a lot of opportunities for us.
And there is also a risk - the risk of putting something live as-soon-as-possible because
everybody else is doing it.
So, we have been pushing and nudging people to see APIs as a product - to think of them as
a market opportunity and not just a technical artifact that you deploy whenever you feel like
Because we believe that API design is not just to be left to techies - it involves more people!
Two strategies - inspiration and perspiration to determine our success - the proverbial
carrot and stick.
The inspiration is about understanding business, understanding technology and using Design
Thinking to merge them given through story telling. And that’s 1% of the success.
And to inspire our Business Audience we talk a lot about API and what business they
I’ll give some examples of some of the trends we observe and touch on in our API Thinking
training - which is also the title of our talk.
Because if you want to talk to the business, you need to understand business. It matters that
you work for a bank, a hospital, a energy company, an insurance company or your own start-
up. Even though a large part of your skills may be transferable, the better you are able to
articulate the value your projects brings, the more serious people take it.
In every case we, the engineers, need to understand the business, the risk, the incentives
and the ethics to be able to design resilient systems and thereby good APIs.
We want to be where our customers are. A way to ship small parts of our brand and services
not only as the whole website
– in this setting “APIs are brand atoms” – that smallest piece of shippable functionality.
Joe Pine - commodities, goods, services & experiences. People are willing to pay the most
comes with a change in mindset - be where your customers are, not the other way around
The key take-away of our training is that you need to understand WHY your API is here.
What value does your API bring to your customers?
We spend a lot of time on this question.
Because we’ve learned that the better you can explain why your API is here - the easier it
become to answer the question ‘is this a good API?’.
Only the WHY question is difficult.
People assume everybody already knows this - and never talk about it
People don’t really know it and avoid the question
It is in these translations, hand-overs and awkward moments between teams that a lot of
information is lost. And it becomes harder and harder to design a good API.
You have two groups in front of you, developers who think it doesn’t really matter for which
company they work because their skills are transferable. And business that thinks IT is a
cost-center. you both need them!
Have you every tried putting 9 people from different backgrounds, languages & walks of life
in a room with the assignment: go and create? This doesn’t happen! How do you go an get
them to mingle?
This is where the 99% comes is: perspiration.
We know we are attempting something brave. Facilitation techniques
We are currently experimenting with these forms. Small steps to make it manageable.
We have teams create a Design Challenge and fill in the Business Model Canvas.
The Design Challenge is a well known term in the Design Thinking community.
It was coined by IDEO and it’s primary goal is to make sure you understand what problem
you are solving and the make sure all people agree that this is indeed the problem we need
It answers four questions
And because you are creating a shared understanding of the problem between all members
of the group, this leads to less ambiguous decision making and thereby a reduction in risk.
Because if the problem you are solving isn’t clear, no one is deciding. Things just happen -
for better or for worse.
Let’s look at some of them..
Is our API cohesive?
So think about the basics interactions for your API. If you create something, can I retrieve it.
Is there a GET for every POST? Can I get the list of things?
Do the operations and functions cover the entire domain or have you a made a very narrow
solution of one specific problem?
Going into the values and principles you want to codify?
You might have received an regular flow of Privacy Terms update emails. GDPR. This effects
how we store data, and our perspective on privacy.
How do we monetize our API?
Don’t hide behind internal usage: use this time to calculate the ROI and learn something
The better you understand what value your projects brings, the stronger your career
negotiation becomes. What if you’re project looses all the money?
The notion that software engineers are not responsible for things is an illusion we’ve
held for a long time and must be put to rest for good.
So API Design starts with the incredibly hard WHY question..
To support this question, we need to shift our developer portal once again. And you may
remember our developer portal which currently places Open API Specification files at its
This will help us track the life-cycle of APIs and coach teams in creating beautiful products.
Going about answering the WHY question is an uncomfortable feeling. Remember this
You need to tell people it’s ok to feel like this.
This is the shift we are making. Shifting API design from tech to business.
It will be ok.
> Just like I felt in my coffee journey.