API Governance model at Platformable
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.
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
|Tool||Description||Links for information|
|Team Topologies||A model of how to structure teams and encourage communication within an organization so that centralized (platform) approaches for developing common tools are balanced with supporting lines of business to continue to produce at pace autonomously and drawing on their own subject matter expertise|
|Inner Source||An approach to sharing information and best practices internally in a similar manner to open source methodologies|
|Paved roads/ golden paths/ common patterns||A series of patterns and tools that assist developers to get started on new projects or replicate common tasks without having to reinvent the wheel or leave their flow in order to create the foundational elements needed for their next project|
|Developer personae||Templates that describe key characteristics of developers that will use APIs. In some of our most recent work, we have found that it is less important to know drivers like preferred programming languages and instead understand their workflow/use case needs and toolset|
|Internal Developer Portal||An interactive, engaging internal catalogue and portal site with access to web services, internal APIs, documentation and so on.|
|Standards, style guides and security requirements||Consistent terminology, structures and data models to describe datasets, data objects, and API processes. Standards are industry-wide approaches whereas style guides may be internal to an organization or team.|
|OpenAPI Specification||The OpenAPI Specification is an open standard that can define an API. It can help business and technical leads to agree together on the API functionalities and address exposure risks. It can be used in automated testing, deployment and interactive documentation generation.|
|API design, lifecycle and testing tools||Tooling to enable best practice processes, automation, and team collaboration when building APIs. We regularly assess and suggest a range of tools for our clients including Stoplight, Postman, APIwiz, and SmartBear.|
|Product management||An approach in which APIs are recognised as ongoing products with audiences. As a result, APIs will require maintenance, ongoing interaction with users, and continued improvement over time.|
|Data governance||Data governance consists of the policies and processes that ensure that data is managed ethically, responsibly and securely within an organization and with partners.||https://platformable.com/products/data-governance|
|Legacy/ new build streams||Existing APIs are known as legacy APIs and come with some technical debt (that is, they cannot be updated without impacting users and existing infrastructure, despite possibly not using current best practices or organizational style guides and industry standards). New builds are APIs that are introduced after API governance processes have been formalized and agreed within an organization.|
|Documentation sites and wiki pages||Documentation sites and wiki pages are content and knowledge management systems designed specifically to make it easy to share processes and best practices internally and amongst users.|
|API Catalogs||Intranet- or external-facing sites that document all available APIs in one place|
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)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
|Stage||Description||Key stakeholders||Supporting tools|
|1||Project kickoff/ initiation||Organisational C-level Executives, Senior Architect, API consumers|
Governance committee organisational structure, Calendar of future API builds
|2||Requirements gathering||Senior Architect/ API Team Lead, API Product Manager||Templates to support requirements gathering, Developer persona templates, API Playbook|
|3||Analysis||API Team, API Product Manager||Existing API taxonomy and functionality, existing data components library, internal developer portal, API Playbook|
|4||Design||API Technical Team, API Product Manager||API design tools, API linter, API Playbook, style guides & standards|
|5||Testing||API Technical Team, QA/Testing Team||API testing tools|
|6||Deployment||API Technical Team, API Product Manager||CI/CD tooling, External developer portal, API Management solution, API Playbook|
|7||Maintenance||Product Owner, Technical Owner, API consumers||Product roadmap tools, service/support tooling, API Playbook|
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.