API governance maturity

API governance aims to ensure that you get the full value from your APIs. For organisations supporting internal API developers, that means taking a platform approach and reusing composable components (APIs and data models) to build applications and workflows across lines of business. For organisations that are exposing APIs to partners and other external users, it means making sure that there are no barriers to building out an ecosystem where your API consumers can collaborate and co-create using your digital components and assets.

Our API governance toolkit includes a best practice model that reflects current industry thinking and has been tested with clients from a range of contexts: startups and scale-ups, multilateral organisations, and larger enterprises.

API governance is more important than ever for any digital business. The number of APIs being created by organisations are growing, increasing complexity if they are not standardised or designed in a way that aids reusability while ensuring security.

But for organisations that already have some APIs in place, or who are now dealing with wanting a more cohesive effort around their APIs, how do you identify where you are at and progress along the governance journey? Our API governance maturity model aims to help you strategise and take action.

API governance for the AI age

As some organisations start to test AI elements and solutions either in their products and services or in their automated workflows, the potential to use APIs also increases. New API integration patterns are emerging like the model context protocol (MCP), which provides a standardised way for AI tools such as assistants and agents to consume APIs. As Kevin Swiber recently pointed out: 

This means that APIs need to be more easily understood by machines by using consistent design and naming conventions and applying industry-wide best practices so that APIs are easily consumed by this new class of API users.

Our API governance model describes a framework aligned with the software development lifecycle that describes various elements that can be introduced so that more standardised, performant APIs can be created and product managed within an organisation.

But where to get started? Most organisations already have some APIs and some processes aimed at supporting API developers. How do solution architects, API team leads, a CTO, or a passionate API champion start from where their organisation is at to introduce API governance? Our API governance maturity model helps you take stock of where you are and apply actions that help you move forward strategically and efficiently, focusing on quick wins and ensuring you are working on the areas where you can move the needle.

Maturity Level 1: Fragmented process

At the first level of maturity, organisations tend to have a disparate set of processes in place, more focused on supporting API development on an individual basis rather than encouraging any consistent processes or approaches.

Perhaps there is some use of an API specification such as OpenAPI. There may be some simple style guide rules that are used at a team level, or even by individual API developers who reuse their own naming conventions or data models in multiple APIs. There is usually some sort of integration testing done: with tests written for the specific API being developed. When it is ready for deployment, it is made available on the API gateway and surfaced inside an API management platform — if one is being used (the majority of our work on API governance usually involves working with organisations that either have an API management solution, or who are starting to use one and therefore API governance questions start getting raised as they try to list their APIs in the management solution).

What to do at Maturity Level 1

For someone starting out at trying to encourage more consistent API governance across the organisation, at this stage it is important to review existing APIs and see how they are built, what commonalities they share, and what API creation/testing/deployment processes each API team uses. Try and document the current situation. Start to identify commonalities/repeatable processes and informal rules and norms being used.

Where possible, take note of API success stories where you hear of them: high performant, high volume APIs that add business value. Do these APIs share anything in common? For example, do they have consistent naming conventions or reuse data models? Are they all targeted at specific audiences? Do they all have API specification files? In other words, are there any indicators that API governance-like approaches are part of the reason for the success of these APIs? Don't try and force that narrative if it doesn't exist.

Another angle to take would be to look at the naming conventions and data models of these high volume APIs to make a later case that other APIs should follow the approaches of these APIs as these are the ones most developers are familiar with.

Maturity Level 2: Consolidating and streamlining as-is

Deciding to focus on API governance marks the beginning of maturity level two. At this stage, someone within an organisation (you?) is seeking to encourage a more consistent approach to API design, development, deployment and management for some reason. 

Let's break this last sentence down:

"Someone within an organisation (you?)": Let's assume you have found this article because you want to progress API governance at your organisation. We tend to find that you probably come from one of three roles:

• You have been delegated organisation-wide responsibility for implementing an API governance framework or approach across the organisation
• You work in a platform or enablement team and you need to build or socialise an API governance approach  across the organisation
• You work in an API team within an organisation and are frustrated by the complexity and messiness of how APIs are created independently in each line of business and you want to propose a better way.

To plan a way forward you need to understand your overall organisational context (see below discussion).

"...encourage a more consistent approach to API design, development, deployment and management": Our full API governance best practices model describes how governance impacts on each stage of the API lifecycle. The goal is to implement API governance in a way that enables automation wherever possible and reduces the bureaucratic bottlenecks that come from review processes.

To plan a way forward you will want to understand the full API governance model and identify what you see as the opportunities to work on from your role and position. We discuss this further below.

"...for some reason": Understand your motives for wanting to encourage more robust API governance approaches across your organisation. You obviously believe in the benefits that will come from API governance: whether that be greater developer productivity (perhaps even your own interests in staying in your flow), faster time to market, more secure API design, or so on. Understanding your motivations helps because you may need to be aware when you are arguing for the benefits that would help you rather than the benefits that would help the decision-maker you are trying to convince. Are you taking it personally or arguing from the wrong base? What would the people you are trying to convince get out of better API governance?

Below we discuss how to draw on existing organisational policies to explain 'this is why we are empowered to do this' or how to create a set of benefits and advantages from API governance that you can use to advocate for API governance if there are not clear policy statements.

What to do at Maturity Level 2

1. Understand your organisational context

It is important at maturity level 2 for you to reflect and identify the role you can play, and the organisational context that you are surrounded by. API governance implementation is just as much about the organisational culture as about the technical solutions, if not even moreso. So start by understanding what you are working with. In general, there are three types of organisational context:
 

It is important to understand your context because it will help you understand what is possible to influence. (This process mirrors our ecosystem design thinking as well: we encourage those organisations seeking to build or enter digital ecosystems to first understand what role they want to play in an ecosystem, and understand what levers or functions they have available to them.)

If you work in a centralised context:
Depending on your role, you will have more or less influence opportunities. 

If you have been delegated or been able to take on a leadership role in your organisation, you may have the ability to introduce an API governance framework for the whole organisation. You can establish a governance committee that includes solution architects from across lines of business, and include business leaders who are focused on platform or ecosystem capabilities for your organisation.

If you are a champion for API governance but do not have that leadership role but work in a centralised organisational context, your goal is to encourage C-level decision-makers to prioritise API governance. You may need to share successful stories of other organisations with a centralised structure and describe how they have benefited from a move towards API governance. You may need to identify examples from your organisation's API portfolio to show how greater standardisation in API design, or reuse of data models, or use of a linter, etc has led to those APIs being of greater value than ones that did not take that approach (be careful not to blame the API dev teams that created APIs that didnt use standardised approaches). Your goal here is to encourage those with authority to see the value in starting an API governance initiative across the whole organisation.

If you work in a federated context:

If you are a solution architect or lead in your line of business, you can introduce API governance characteristics for the team or teams you oversee. For example, you can start to create a line of business style guide, create a linter that all your API devs can use, and so on. You may have some authority in enforcing that style guides and a linter be used.

You can use inner source principles to share your work across other lines of business, and share your approach with other lines of business.

If you are in an API dev team in a line of business, you may have less power to encourage adoption of a style guide or linter. Again, inner source approaches can help. Your focus needs to be on sharing the approach of your team. You may need to collect data on the value you are generating. This might include time saved by using a style guide or reusing data models in your APIs, overall time from API design to deployment, or showing faster user adoption of your APIs after you release (especially if the APIs are monetised in some way). You may need to accept that change may happen slowly outside of your team. What we find is that there may look like there is no appetite for moving to an API governance approach. But by modeling behaviour in your team and having metrics that demonstrate the value your team is creating, appetites can change overnight. Think of it as having a proposal in your back pocket. Keep advocating for the benefits your team are seeing from standardising API approaches and when the moment is right across the organisation, you can present your arguments. As they say, "if you stay ready, you don't have to get ready."

If you work in a platform/enablement team context: 

Your organisation has a somewhat hybrid approach. In a recent webinar with Tyk, those attending were mostly from a centralised context. But when I have presented on API governance at API Conference events, the audience has mostly been from this hybrid approach: over the past few years, the Team Topologies model has caught the attention of many enterprises, and the shortcomings of a fully centralised or fully federated approach have been acknowledged. A move has been made to centralise IT operations and take a platform approach where lines of business are supported by a central team that manages shared tooling, the API management solution, and so on. 

This team may be responsible for creating an organisational wide style guide and other API governance artefacts, and an enablement team then supports individual line of business API teams to adopt the style guide or other standardized processes. Often the enablement team needs to be able to socialise and promote the platform-based approach but does not necessarily have authority to enforce use.

2. Understand your role

Understanding your context helps you think through how much you can shift, and what strategies you will need to adopt. Work within your sphere of influence and model behaviour and work with your team. Some API devs have such little influence in API governance that they have simply started by sharing a wiki together of naming conventions and data models they reuse in their APIs, or they create a list of the core tools and services they rely on whenever they are starting a new API project (like a mini-golden paths document).

3. Identify what levers you can influence

Compare the full API governance best practices model with the maturity level 2 model.  Identify what areas of an API governance approach you might work on next. We would strongly recommend having a list of the benefits, or knowing what organisational policies support improving API governance (see discussion below). Following this, when looking at what area to work on, you may consider the organisational context (above), your role and potential sphere or influence (as discussed above), what current API-related projects are occurring across your team, one of business or organisation (what would support your work the most next?). Look for quick wins, where tidying up existing approaches (such as turning informal team notes on naming conventions and data models into a wiki sharing an informal style guide) or areas where teams would appreciate some help (such as starting to build a more standardised set of integration tests that could be used with all APIs under development, or a wiki with a list of public linters and API health tools like Treblle's API insights or the open source OWASP assessment ruleset that could be used to encourage best practice adoption).

4. Be prepared to describe the drivers and benefits

At this level of maturity, we recommend you write or refer to a statement that describes the value you are trying to get from a more streamlined, standardised approach to API governance. Where possible, try to use organisational policy statements where they are available. For example, perhaps a C-level leader has made statements about creating an ecosystem, or moving to a more efficient approach of sharing IT resources across the organisation (a platform approach). Perhaps in your business plan it describes these as goals. A core architectural decision team or IT governance committee may have passed a resolution to adopt standards or common approaches or improve efficiencies or so on. Where you do not have a centralised approach or C-level champion for API governance, identify if there are any supporting documents/policies that reflect the goals of API governance. In addition, you may want to list the benefits that can be generated from API governance. Use the metrics you have been collecting from your own API experiences. As part of our API governance toolkit, we are releasing a cheat sheet of value statements you can draw from. You will want to memorise these as you speak with colleagues and decision-makers, highlighting the benefits of moving towards clearer API governance across the organisation.

At this maturity level, we often see more structured approaches to APIs: there may be more formal decision processes to create APIs and allocate them to dev teams to build (rather than API dev teams deciding themselves that the best way to solve a tech problem is to build an API). There may be some externally published APIs and some minimum documentation that is provided to partners or third party API consumers. There may be regular use of OpenAPI Specifications or other API description standards, and some design tools in place.

Maturity Level 3: Building consistency

At this level of maturity, you have a range of processes in place across the organisation (and/or line of business) that situates API decision-making in a wider business strategy context.

There is an organisation-wide or line of business approach in which the decision to create APIs is strategic, with clear links between the decision to build APIs or extend featuresets because there is a clear expectation of the value and business opportunity this creates. There is usually some sort of budget applied, or recognition that resources are needed to introduce and encourage API governance practices. There are common platform tools used, including style guides, perhaps a playbook that documents API best practices, identified design and testing tools, API management solution which includes features that enable internal APIs to be catalogued (this may require additional identity access management policies) or an internal developer portal (or even a wiki) with internal APIs and (hopefully, although probably not at this level) common data models that can be reused. When APIs are added to external portals, there is minimum documentation including interactive documentation where users can make API calls directly and see responses. 

What to do at Maturity Level 3

At this stage, it is worth looking over the API governance best practice model and thinking about it a little more as a process: are there tools and support structures that start to help devs work in a flow from one step to the next? What can be automated?

Use your budget to map out what actions you will take and what resources you will apply to make it happen.

Maturity Level 4: End-to-end automated governance

At this level of maturity, APIs are treated more often as products (with the caveat that not all APIs need to be treated as products), and automated. 

What to do at Maturity Level 4

Focus on autoamtion and using insights and analytics to implement product management and API maintenance approaches.

If APIs pass linter assessment, automatic generic tests are run before any bespoke testing is needed, and after testing, if all passes, can deployment occur automatically?

There may also be semi-automatic processes, for example, data on usage, error rates and API consumer experiences could be drawn on for analysis when designing new features or looking at new APIs for the same developer segments.

While personally, I try and encourage a developer-consumer mindset from the beginning of an API project, in reality I haven't really seen that happen. It is more that when there are enough APIs and an organisation has matured enough to consider their API portfolio as a business advantage and is on the road with some of the previous levels of maturity that they begin to introduce a product management approach that starts considering the needs of API consumers. This is in part why we have added the developer-consumer focus (whether at the commencement of an API project, or at the end when building in maintenance activities like managing a roadmap) to this final stage of full maturity.

Using this maturity model

We are developing a self-assesment tool for you to better identify which of these stages of maturity you are at, and where the potential quick wins for you could be. 

We will also revisit our API governance toolkit and model and flesh out resources for each stage we describe.

For example, we are building some templated tools including an API playbook template, OpenAPI Specification template, a linter directory and guide, and a self-paced course for API governance leads. If you are interested in API governance practices, we also strongly encourage you to sign up for Ikenna Nwaiwu's newsletter, join the API Evangelist's Weekly Knowledge Builder Sessions, and keep an eye on the articles by Jennifer Riggins who often explore the nexus between API governance, platform engineering and developer productivity. 

We also have a specific API governance tool we think the industry needs, we would love to discuss with potential partners our ideas for this tool.

If you would like to get involved or gain early access, please reach out.