Open Ecosystems

Platformable logo
Understand
watch14 min read
email

API Governance model at Platformable

Written by Mark Boyd
Updated at Sun Sep 10 2023

Who should read this:

CTOs, Senior Architects, standards leaders, platform engineers, API product managers and anyone in an organisation responsible for ensuring that APIs will generate value for users.

What it’s about:

API governance is an increasingly important practice as your organisation needs a way to reduce the complexity of your APIs and make it easier for internal and external developers to make use of the multiple APIs available.

Why it’s important:

Without API governance, AI sprawl creates too much complexity. Internal developers end up duplicating API creation rather than grapple with understanding existing APIs, and external developers choose a different API provider or limit the use of your APIs. For internal developers, this slows down product development velocity and increases tech costs, and for external developers it reduces potential revenue that can. be generated.

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.

platformable

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.

 

Open ecosystems

Platformable's definition

An open digital ecosystem is a network of equitable participation opportunities that allow stakeholders (including multilateral organizations, governments and regulators, associations, industry enterprises, small and medium enterprises, researchers, nonprofits, community groups and individuals) to co-create, collaborate, complement, and/or compete with each other by using common tools (including APIs, open standards, open data models and open source tools) and shared infrastructures.

 

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:

API governance is establishing and overseeing decision-making, policies, practices, processes, and institutions to enable an organization’s people to collectively achieve its goals by efficiently taking advantage of private, partner, or public APIs. It aims to align APIs with business and IT strategies, to monitor and maximize the value created from them while identifying and addressing risks and ensuring compliance with regulations. API governance is enabling and facilitating people to work together on the right APIs, the right way to maximize the value created by APIs in alignment with the organization’s goals and constraints.

Arnaud Lauret

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

API lifecycle management helps with improving an API’s value, while API governance helps with improving the value of the entire API landscape.

Robert Kimani

 

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
ToolDescriptionLinks for information
Team TopologiesA 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

https://teamtopologies.com/

 

Inner SourceAn approach to sharing information and best practices internally in a similar manner to open source methodologies

https://patterns.innersourcecommons.org/

 

Paved roads/ golden paths/ common patternsA 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

https://thenewstack.io/the-cloud-native-paved-path-developer-experience/

https://cloud.redhat.com/blog/designing-golden-paths

https://kgb1001001.github.io/cloudadoptionpatterns/Strangler-Patterns/Pave-the-Road/

Developer personaeTemplates 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

https://www.slashdata.co/blog/developer-personas-revenue-growth-tool

 

Internal Developer PortalAn interactive, engaging internal catalogue and portal site with access to web services, internal APIs, documentation and so on. 
Standards, style guides and security requirementsConsistent 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.

http://apistylebook.com/

 

OpenAPI SpecificationThe 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.

https://www.openapis.org/

 

API design, lifecycle and testing toolsTooling 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.

https://apilandscape.apiscene.io/

 

Product managementAn 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.

https://medium.com/capital-one-tech/the-role-of-product-management-in-api-design-988f295b989

 

Data governanceData 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

 

Legacy/ new build streamsExisting 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.

https://open.substack.com/pub/mamund/p/guide-implementations-with-the-ease

 

Documentation sites and wiki pagesDocumentation 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 CatalogsIntranet- or external-facing sites that document all available APIs in one place

https://www.digitalml.com/resource/build-vs-buy-api-catalog/

 

 

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. Wee 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
API governance best practice model diagram.png
Table 2: API governance model stages
StageDescriptionKey stakeholdersSupporting tools
1Project kickoff/ initiationOrganisational C-level Executives, Senior Architect, API consumers

Governance committee organisational structure, Calendar of future API builds 

 

2Requirements gatheringSenior Architect/ API Team Lead, API Product ManagerTemplates to support requirements gathering, Developer persona templates, API Playbook
3AnalysisAPI Team, API Product ManagerExisting API taxonomy and functionality, existing data components library, internal developer portal, API Playbook
4DesignAPI Technical Team, API Product ManagerAPI design tools, API linter, API Playbook, style guides & standards
5TestingAPI Technical Team, QA/Testing TeamAPI testing tools
6DeploymentAPI Technical Team, API Product ManagerCI/CD tooling, External developer portal, API Management solution, API Playbook
7MaintenanceProduct Owner, Technical Owner, API consumersProduct roadmap tools, service/support tooling, API Playbook

 

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.

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.

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.

member image

Mark Boyd

DIRECTOR

Article references

1

Platformable value model: We will be adding more API governance resources over the coming months to explain how to implement actions at each stage in order to build the artefacts that support your governance processes.

Related article