Sophisticated API Taxonomy – A Must Have For API First enablement

This article discusses the meaning of API taxonomy. It also explains how some companies succeed in being digitally savvy and succeeding in their digital transformation journey, while others are struggling to show some progress in the digital transformation journey.

Some companies, like Uber, Stripe, Spotify, etc., are succeeding in digital transformation. What is it that they do differently?

A company starts as a start-up, and then we scale the company. As it grows, it tends to slow down and becomes less efficient. It takes more people and money to get things done right. Employees start to look inwards toward their own departments and groups. They lose customer focus. Interaction between teams also becomes a challenge.

When such companies create APIs, everyone creates APIs, and the need for API Management and API governance arises.

Confucius says, “If names be not correct, language is not in accordance with the truth of things. If language be not in accordance with the truth of things, affairs cannot be carried on to success. The beginning of wisdom is to call things by their proper name.”

He is saying that, if names are incorrect, affairs cannot be a success. So, the beginning of wisdom is to call things by their proper names. This is an emphasis on taxonomy.

Taxonomy is the science or the law, or the principle of classification. It’s an ordered system you start to bring order to a chaotic system by classifying things.

API taxonomy is the beginning of wisdom in API management. It is to be able to have those metadata and all the different categories and buckets where you could organize your APIs.

How do you name your APIs?

Does your API catalog reflect good meaningful API names? While looking at an API catalog, how do you know what the API does? Here the correct name plays a large role.

Do your developers give a proper business-aligned name to your APIs?

Do you meet for a long time as a group to pick the “right” API name and still struggle?

Can you keep up with the number of APIs? Or have you given up on reviewing the names of your APIs? Considering the explosion in the number of APIs, it is very hard to scale that process if the APIs are not named correctly.

Remember –

• Bad names are confusing
• Teams struggle and need help picking meaningful names
• Hard to scale the process of reviewing all API names.

The next point to consider is that even if there is an API with a relatively perfect name, it’s very hard to tell whether it’s a duplicate. Maybe the duplicity is required, but we need to be able to tell the difference, and the name alone will not tell me that. So, I would need more metadata and more self-explanatory information to tell if I need to develop a new API, or I already have it, or I need to enhance an existing API.

Developers will learn about APIs and their capabilities by visiting an API catalog. An engineer would learn more about a business domain by looking at the collection of APIs more than by any other means.

APIs are all about advertising and communicating a business capability or our technical capability. So, putting those APIs together to advertise a certain capability and to be able to communicate the contract about that capability, an interaction model with the business or technical capability, makes a lot of sense to many of the developers.

In large organizations, changing behaviors is the hardest part. Here, when we talk of behavior change, we are talking of standardization across the organization. So, we need to convince and change departments or groups with their own standards and move them towards organizational standards. When you need to change certain behavior –

• Bubble it up in the taxonomy
• Teach it
• Measure the change of behavior of how people are using it.

Then you can adjust based on the measurements. This will drive the change of behavior, and it will drive commitment.

The purpose of driven or sophisticated taxonomy is to design the taxonomy in a way that we identify the areas of focus and struggle and put them into the taxonomy.

Some of the sample outcomes of sophisticated taxonomy are –

• Better business alignment – Each API must belong to a well-defined business domain
• Driving agility and the right level of governance – Distinguish between reusable APIs and private APIs
• Operational maturity
• Secure data classification
• Built-in security
• Clean design
• Better discoverability