API geeks love a maturity model. We’ve had a few come through over the years, such as Richardson, Admunsen, and the recent Curity API Security Model. By critically looking at both the style and properties of the APIs we create, these models give us valuable insight as to how we are progressing in our journey to becoming API gods and goddesses.

This love of maturity models comes as a surprise given how immature most of us software people are. Pop Funkos, lightsabers, Star Wars T-shirts… all the hallmarks of not wanting to grow up, enjoying the artifacts of geekery that are a reflection of how we thrive as designers, developers, or whatever we like to label ourselves. Our working lives revolve around our Extended Universe of knowledge that comes with proficiency in our favorite programming language. Perhaps it’s time to reflect on ourselves and our levels of maturity as human beings rather than just producers of APIs?

With this in mind, this post proposes a new maturity model: one for humans. In it, we’ll explore how we develop as API practitioners in terms of the growth in both our skills and consciousness rather than the properties of the APIs we produce.

Getting Started: “Acquire” a Model

API Maturity for Humans was inspired by the levels of cognitive development detailed in Things That Make Us Smart, by Don Norman.

True original thought is a commodity that’s hard to come by. Thus, taking the ideas of other people and extending them or contextualizing them for one’s own purposes is fairly typical. API Maturity for Humans is no exception. It mimics a model of cognitive development proposed by Don Norman in his book Things that Make Us Smart, which in turn built on one created by Mervin Donald in Origins of the Modern Mind. I’ve then applied it to how we grow as API practitioners.

The model proposes four stages of cognitive development during the evolution of human beings, namely:

• Episodic (called Experiential by Don Norman).
• Mimesis.
• Mythic.
• External Representation.

Each of these phases in human development took many millennia. However, the spirit of each – which we’ll discuss below – can be applied to how we gain and hone our skills as API people.

Phase 1: Episodic

In the original model, the Episodic stage was envisaged as happening when we transitioned from the common ancestor we share with apes to early humans. The development of the early human brain was influenced by events – “episodes” – that changed our ancestors’ understanding of the world around them: The effect of the elements, threats to safety, and interactions in the landscape all played their part in the development of consciousness.

The API perspective on this is characterized by the need to “start somewhere.” For new entrants to the API economy, the Episodic phase is the start of their development as practitioners, where an event triggers their API “consciousness.” It may be an interaction with a colleague, reading a blog post, or a new product feature that triggers it. It could be the result of trying to solve a problem or to improve business. The net result is an awareness of what an API is for and why it is important.

There are different courses for different horses here, and awareness is likely to reflect your chosen profession. A software developer, for example, will appreciate an API more quickly and in greater depth than a product manager and hence may transition through the Episodic phase more quickly. Moreover, being a software developer, they will have the means to act on it in their day-to-day job.

However, the Episodic phase is essential simply from the fact that would-be practitioners can start to use APIs as an affordance to their work. Acting on that awareness begins to manifest itself concretely in the Mimesis phase.

Phase 2: Mimesis

Donald envisaged Mimesis as the stage at which humans started to act – mime – as a means to help communicate their wants and needs. Through doing this, they began to turn their internal representations – their cognition of a given event or activity – outwards, helping them establish the rudiments of language. Don Norman defines this as the time when “sophisticated communication and mental states become possible.”

In the world of APIs, our would-be API practitioner starts to do the same thing, using their newly found awareness to design, build, plan or strategize on APIs, miming their internal representation to communicate their ideas to others. Their perceptions have limited context; they know what they know from those first episodes and will almost certainly use prior experiences to inform how they approach the task ahead.

This limited context can lead to the Dark Side of Mimesis, namely the propagation of API thinking that uses internal representation as the primary influence. Examples of the dark side are pretty apparent to the initiated. The cardinal sins of API design anti-patterns, for example, manifest themselves in the Mimesis phase:

• Verbs in the URI
• everything is a POST
• All responses return 200 (errors and all)
• etc. etc.

It’s not just newbie API designers and developers that are drawn to the dark side. The less hands-on architects, product owners, and executives can fall victim too. Take this phrase, for example, oft-repeated in organizations but seldom uttered in public:

“Well, we have interfaces for our messaging on [insert name of platform]… so really we’re already doing APIs aren’t we?”

Semantically the statement could be considered true, but it divests the speaker of committing to embrace open APIs, justifying and reinforcing the status quo as a “win.”

The dark side of Mimesis, of course, hasn’t won the day. The API Economy continues to flourish, and that is mostly down to practitioners learning both from their own experiences and from others. That learning from others leads us on to the next stage in our development as API people, the Mythic phase.

Phase 3: Mythic

Mimesis is – of course – insufficient for humans to communicate anything but basic information. There is no means to use intonation or expression to convey subtly or nuance. In Donald’s model, Mimesis is therefore supplemented by the development of language and increasing richness and sophistication in the communication of concepts and breadth of vocabulary. The sophistication that characterizes this phase is achieved through the mythology or – more plainly – storytelling.

Storytelling has always been fundamental to how we learn and – as the internet has grown – been important to our learning as technologists through blog posts, how-tos, and so on. This means of storytelling has always existed during the growth of the API Economy. However, the characteristics of the Mythic phase have changed as the API Economy has developed. When Web APIs started to become popular basics of language we share – architectural styles such as REST, constructs that were later embedded in specification languages like OpenAPI Specification – were not ubiquitous. As a loose group of practitioners, API providers, and developers consuming those APIs needed to develop a lexicon to interact using common terminology.

With time these technologies and the vocabulary around them have become the bedrock of our knowledge, and API practitioners and providers reinforce the experience through the same act of storytelling and the sharing of a collective monolog. This act of storytelling also creates and strengthens community; without it, the API Economy as both a concept and a reality would not exist.

The Mythic phase, therefore, helped build the foundations of the shared language of APIs. This increased maturity naturally led to the fourth phase of our development as API practitioners, that of External Representation.

Phase 4: External Representation

In Donald’s model, External Representation is when we become modern humans, with writing and tools to support our continually developing minds. Norman calls these external devices “cognitive artifacts” and highlights them as offering the means to go beyond our “biological heritage.”

It’s not hard to see the parallels with our development as API practitioners. We have an increasingly rich set of tools at our disposal that allow us to be even more effective in how to design, build, and communicate our APIs.

Many of these tools underpin some of the practices that have become commonplace on the API product line, especially API-first design. Examples include:

• Design: Swagger tooling has set the standard for design when using the OpenAPI specification language, but the breadth and depth continue to increase from the likes of Stoplight creating free-to-use design tools that allow API practitioners to model and communicate their API designs in a seamless way.
• Collaboration: Humans need the means to communicate effectively, especially with our increasingly distributed workforce. Ease of collaboration is important at API design time, and tools like SwaggerHub and Postman Collections allow this to happen effectively.
• Exploration: In the most salient model for API providers – where they make information about their APIs available via a portal – exploration is critically vital for developers looking to integrate with a given API. The tools available here are almost too numerous to mention. Still, all of them underpin the portal functionality – and the great portals that are out there – that allows providers to make exploration happen effectively.

External Representation is, therefore, the cornerstone of how we communicate as communities of API practitioners in design, development, and delivery. It supports everything we have learned in our maturation and gives us the means to be at our most productive.

Final Thoughts

In this post, we’ve explored how human beings – both as individuals and as a collective of API practitioners – develop the artifacts to collecting and express a technology phenomenon. Clearly, the underlying models are based on the development of cognitive thought through many eons and the API Economy that has existed for at most tens of years. However, those fundamental elements – an episode or event triggering the development of a consciousness shared amongst a group of people – fits how we develop as technology practitioners, whether in the field of APIs or not.

What the models do not address is how our consciousness will continue to evolve. Will technology such as AI we have the potential to exceed the confines of our biological heritage and develop in ways we cannot foresee (except in the plot of a sci-fi movie)? The most exciting part of this model is, therefore: what happens next?

This post is based on a session held at the ABN AMRO Unconference in May 2019. Massive props go to Koen Adolfs, Product Owner for Open Banking and Enterprise Integration Technology, who organized the event.