API Governance Toolkit

At Platformable, our mission is to support the development of open ecosystems. As part of that, we see standards and consistent design practices as key enablers that help foster digital environments in which stakeholders can collaborate, co-create, coordinate, compete and/or complement each other. API governance refers to the policies and processes that make it easier for API providers to introduce standards and consistent design practices.

A quick aside

My background is in public health, where I ended up working with city governments on population health and wellbeing strategies. Taking a social determinants approach to health, we often focused on place-based approaches (being a city government). We sought to leverage urban planning in a way that made it easier for people to choose the healthier and safer options: whether that be by having walkable streets, reducing the density of fast food and alcohol venues, increasing local availability of fresh food, and so on. One of the foundational principles of this approach is that people will choose the healthier options if those options are the easier and more accessible choices in front of them. API governance is the same: following standards and using consistent design practices should be the easier, more convenient and accessible options to choose when building and managing APIs.

Previous work on API governance

As Director/Founder of Platformable, I have been working on API governance for several years:

• In 2017, I co-authored a paper with Lesley Anne Vaughan for the World Bank’s CGAP initiative encouraging API governance to prevent API sprawl and complexity amongst API providers that could offer APIs to support the development of financially inclusive digital products.
• In 2020, with Lorenzino Vaccari, Monica Posada and Dietmar Gattwinkel I conducted research and ran workshops to map out a governance-focused API framework for digital governments, and tested our model with the help of Marco Panebianco and Marco Ogliari at the Regione Lombardia government in Italy. This resulted in a series of checklists and an online tool which helps governments (but can also be used more widely) to score their API governance maturity across 12 key areas.
• Now at Platformable, we are currently working with private clients from business and multilateral organisations to assist them in moving to an API First approach in which API governance practices are streamlined and are able to support the creation and maintenance of APIs across all business units.

What do we consider API governance?

Arnaud Lauret, API Governance Lead at Postman, has done some ground-setting work on API governance and reviewed various models to define API governance. At Platformable, we use Lauret’s definition:

Writing recently in The New Stack, Robert Kimani helps clarify the difference between managing APIs and API governance: 

API governance toolkit

We draw on a number of tools to encourage organizations to move to API governance (really, API-first) approaches, as described in Table 1 below.

Table 1: Tools we draw on in API governance

The key challenges in API governance

We have the tools and even the practices to support more cohesive API governance. As always, the most difficult aspect of implementing API governance is supporting the people within an organisation to shift towards this approach. We hear common reasons why it's not possible:

• There is not a global cultural mindset within the organisation to move to a platform/ecosystem approach and while the top-level agree and have often green-lit a platform philosophy, and the technical (bottom) level would prefer it, the middle management level has too many other priorities to stop and consider how to reorient their whole line of business or sub-department to such an approach 
• There is no budget to move organisationally towards API governance. For example, we are hired to work with organisations to introduce API governance, and this may come out of a centralized IT department but when we speak with API developers within lines of business they ask against which line item in their budgets they should allocate the time for the hour we need to talk, and whether it should be a priority against their other work (which often may include building new APIs!) 
• The organisation only has a small number of APIs so it is over-engineering to introduce these systems
• No one has the time
• The APIs the organisation uses have worked well for the past 5-10 years and only need minimal maintenance or upkeep 
• “We understand our customer and developer needs already”
• APIs are seen as a technical concern so there is no business discussion on the intended value to be generated or cultivated from APIs. There is no way to measure what impacts API governance will bring in so there is limited opportunity to prove the evidence-base for moving to API governance.

We find our main challenge when trying to introduce consistent API governance practices is that people fear over-engineered, bureaucratic models. They are worried this will stop developer flow by enforcing standards and processes that don’t accommodate the edge cases in each line of business that might need to be taken into account when building a new API.

Platformable’s API governance model

We have mapped out the ideal state for how APIs are built and managed within an organisation, drawing on API governance best practices. We also show key artefacts and tools that can be created at each stage to support governance (see Figure 1)¹. In Table 2, we describe each step of the model, key stakeholders involved, and what artefacts and supporting tools are used at each stage. While our model looks linear, in practice, organisations already have a number of APIs in place, so part of the shift towards API governance is to assist mapping current APIs and seeing how they can be drawn into a more cohesive model, without asking teams to revisit and work on APIs that have proven to work consistently for some time. 

Figure 1: API governance best practices model

Table 2: API governance model stages

Next steps

While we continue to improve this approach by implementing the model with our clients, we are also working on new ways to support stakeholders in open ecosystems:

Tooling: We will be creating a learning management system, workshop and miro board materials to support other organisations to implement this model. Please get in touch if you would like to roadtest these new resources as they are developed, by joining our waiting list.

From governance to platform engineering: We see API governance as intrinsically linked with data governance and DevOps processes. We are excited by the emerging thinking around platform engineering and will be repositioning our API governance models within a wider platform engineering context, so look out for a more detailed process map and diagram of how we see all of this fitting together as we continue to work with clients and teams.

Measuring impact: We measure the effectiveness of our client work and are seeing some success. In 2024, we want to revisit our data model and better document the successes and impact of our work. We currently draw on the maturity scorecards created for the European Commission’s API Framework for Digital Governments, but will further adopt these to meet wider organisational needs beyond government.

The future of API governance: Platform Engineering

I often talk about how APIs are “the tail that wags the dog”. Introducing APIs in a technical infrastructure moves an organisation towards platform business models and ecosystem relationships, which can fundamentally alter the whole business. It means redefining revenue streams, reorienting organisational structures to meet these new business models, creating API product approaches, prioritising resources available to developers, encouraging business owners to work more closely with technical teams and so on. All of this together is often referred to as “API First”, but in many ways it also reflects what has been increasingly referred to as “platform engineering”.

Platform engineering builds on a DevOps approach to increasingly focus on enabling developers to build in a way that improves overall performance and reduces the need to act on alerts when monitoring. Already, the discussion seems to draw in concepts such as paved roads/golden paths/architecture patterns, and combines this with DevOps monitoring processes. Along the way, we have seen this also incorporate organizational structure reorientations towards the Team Topologies type models (and away from some of the limitations of Spotify squad type thinking which has been predominant in recent years), and also incorporates internal developer catalogs (coincidentally also often led by Spotify with their Backstage open source product). 

At Platformable, we would like to see the next stage of this move towards platform engineering to incorporate data governance: we often see with the clients we work with that API governance and data governance are considered two completely separate work programs. In most organisations we have seen, a move to greater data governance structures is being done as a completely separate track to API governance, despite APIs needing to include data models that need to be consistently defined.

We believe the future of platform engineering is a combination of:

Business policy for ecosystem-based business model + team reorientations and organisational restructures +  Internal developer experience (consistent architecture/design patterns + internal catalog) + API governance + data governance + DevOps = Platform Engineering.

API tool providers and consultants

Get in touch with us

See how to include API governance customisations in your tools so that organisations can more easily implement their API governance strategy. We have helped clients customise their API design tools and internal developer portals, for example, to align with their API governance processes. We have some ideas on features and ways that tools can be improved to make this customisation easier.

API architects and developers

Getting started with API governance

We recommend two key approaches: First, choose one API team that is keen to work on moving towards a more consistent API governance process. Document as you go and share with other API build teams. Gather existing approaches and look for common elements: use developer personae to define what functionalities your API consumers users need, review existing APIs to see which ones offer these types of functionalities, review what existing data objects are relevant to your project, draw on any standards or existing style guides if you have them. What can you use from previous API builds that could work as the start of a common approach across your organisation? Document and share as you go. Learn more about our API governance services.

Product Manager Lead

Getting started with API governance

Define audience personae needs, create developer personae templates if you do not have them and start sharing across the organisation with other API product managers. Assist with identifying the functionalities and data objects from previously built APIs that might be reused in the new API build project. Take a lead on helping document how the API build team is drawing on existing internal resources and start to compile these into a style guide, if one doesn't exist. Learn more about our API governance services.

Data Governance Lead Persona

Getting started with API governance

Review existing APIs and see what data objects are being repeated and which ones are being duplicated. Create resources so that the datasets that are used in common data objects are easy to find. Create a library of data objects and their reference datasets that can be used by any new API build. Learn more about our API governance services.