API Governance Framework

Published: August 12, 2024

Application Programming Interface (API) Governance is an emerging discipline in organizations that own and deploy APIs or services. This post will review the framework Solsys uses when talking to customers about API Governance, our view of API Governance and what it should cover, and how API Governance differs from API Management.

What is API Governance?

Solsys views API Governance as a big-picture program of API management within an organization. It concerns itself with helping the organization to plan for and manage APIs as an asset, and as a class or category of product in much the same way that Data Governance considers the data assets of an organization. This specialized type of product needs to reflect data governance and security policies, while also being easy to discover, use, and access. All of this must happen while keeping the APIs secure, fit for purpose, and consistent where possible. We want to make it easier for our API consumers to find some level of familiarity across our APIs, and ideally only have to worry about managing a single API consumer identity.

With organizations typically consisting of many product development teams iterating to frequently change and improve APIs, these outcomes can be driven by an API Governance team.

API Governance is most successful when it is considered as a service to support the organization. This is best achieved through helping to make decisions about tooling, standards, and practices, and making available information and education to the organization about the development and management of APIs. An API Governance team should work with the organization’s culture to change and improve the organization they are supporting.

CIO’s article discusses API Governance at a higher level, but also gives a bigger picture view of APIs as an organization wide concern.

What about API Management?

API Management is a subset of API Governance. API Management concerns itself with the lifecycle of an API from development and deployment, through to access and retirement (Design and Build through to Update and Retire), and all of the tooling and processes involved in these activities. API Management and the associated tooling is often provided, in part, by API Gateway platforms. There are usually additional tools, or customizations around these platforms, required to support the full API lifecycle, especially for the Design and Build steps.

Here’s how we see API Management and tooling fitting together with the other aspects of Governance in an organization:

What Else Does API Governance Include?

Solsys has developed the following view of API Governance. API Governance needs to consider the following stages and questions, which cover the full lifecycle of an API and the API product set as a whole within the organization.

Security, Alignment, and Strategy

Underlying all API Governance, these three areas are key.

Strategy is about what we build, and why. API Governance teams can help ensure that big picture is considered, and if your organization considers itself ‘API First’, how is that being supported and implemented?

Alignment tries to get API developers (or purchasers) on the same page about what’s important and how to get APIs out there for use. What practices and tools are working well and how are they shared with other teams? What about learning from things that haven’t worked for your organization? Teams often work in silos, and fostering alignment can be beneficial.

Security is perhaps the most important watchword here. Governance must consider that APIs can represent the largest attack vector for an organization, and how will your organization ensure that your APIs are built and deployed securely? We have other posts about improving API security across your development efforts.

Product Planning

API Governance concerns itself with the big picture, and this aspect is all about continuously re-evaluating how APIs are performing for us in the organization, whether they’re returning value, being reused, and where problems and challenges might exist for developers or consumers. This step is where a governance team looks at the current state and considers what needs to be improved next.

Questions to consider:

• How do we, as an organization, interface with APIs as an asset?
• Where do we focus our efforts next?
• How do we see which APIs are performing well from an SLA or reuse perspective?
• How do we consider their use, prioritize development, and improve standards and security?
• How do we intake, estimate, prioritize, perform, and measure our work related to APIs?
• What standards, frameworks, tooling, or other capabilities might we want to develop or improve in support of everyone involved in API development or deployment?
• How does the overall set of capabilities we might want to expose as an organization?
• Will we be generating revenue directly from APIs, and how will we do that?
• Where might we fund or encourage particular API development, improvements, tooling, or management capabilities next?

Design & Build

This is where development teams (or product selection teams) determine what the API is intended to do, define the contract with a specification, validate assumptions with mocks and tests, and document the API. This section is related to the development and deployment of a physical API instance, and associated processes, tooling, and standards.

Questions to consider:

• How can we help teams design and build interfaces consistently?
• Can we help teams with tooling to scan for typical security issues in their code?
• Can we provide testing tooling or guidance to help them?
• What education might we make available to development teams and which ones need the most help?
• What selection or development guidelines will be most useful and help get better results?

Deploy & Secure

This step involves everything related to making a service accessible and protected for properly credentialed consumers. This section considers the approval process and associated policies that should protect any particular API. Often this step is performed via an API gateway platform or similar access point.

Questions to consider:

• Will APIs be exposed for internal consumption, external consumption, or both?
• What platforms or places will APIs be deployed?
• Which security policies/standards will we use to protect APIs?
• What patterns are we exposing APIs under: B2B? B2C? B2E? Other patterns?
• Are there different levels of security depending on API sensitivity or exposure?
• How will we tag or classify API workloads or sensitivity levels, and will these relate to API governance decisions?
• What protocols will we mandate or recommend when exposing APIs?
• How will APIs reflect our zero-trust practices and policies?

Discover & Understand

In this step, teams, partners, or customers are trying to find out what APIs are available, what they can do, and how to use them. Typically this information is captured in an API catalogue tool, as part of an API Gateway platform (on the Control Plane side), but may exist in many places.

Questions to consider:

• How do API consumers, whether internal or external, discover available APIs?
• How will they understand what they do, and how to use them?
• Where is the operational information to ensure we understand SLA, performance, and outage management data for the API?
• What documentation standards might we prefer to use?
• Which APIs should be discoverable, by which groups, and where?

Permission & Access

This stage is about establishing API consumer identities and granting access to specific API consumers. Typically this is performed through an API Gateway control plane tool, but might also involve integration into identity systems across the organization. This section includes the full lifecycle management of onboarding API consumer identities, managing their access, changing and updating credentials, and offboarding identities that are no longer required.

Questions to consider:

• How do we provision credentials for API consumers and permission for them to access specific API(s) or API operations?
• What API identities will be validated?
• How will we review or audit who has access to what?
• Who will be responsible for permissioning access to APIs, is this delegated to API owners or other managers across the organization?
• Will multiple approvals be required for certain types of APIs or APIs with particular sensitivities?

Monitor & Compliance

This step is about monitoring and operating deployed APIs, and being aware of transactions and whether they are secure. We have a post about this step here.

Questions to consider:

• Where and how do we monitor the use of our API assets and ensure they continue to be compliant with the policies with which we deployed and secured them?
• How will we detect and report on potential security issues and support our APIs operationally?
• How do we spot operational or performance issues and reduce time to resolving issues?

Update & Retire

This step is about updating, versioning, and eventually retiring APIs that are no longer needed. Questions to consider:

• When APIs require an update or change, how do we manage this change with versioning, inform consumers, and ensure there are no unplanned outages?
• If an API has reached the end of its life, how is this managed and how are consumers and the API version and product offboarded?

Insight & Reporting

In this step of the framework we are considering how we gather input to help make the planning decisions and we continuously improve our API capabilities and management of our API assets. API Governance is an evolving and ongoing practice, so how do we learn from what’s working, from what isn’t working, and find our opportunities?

Questions to consider:

• As an organization, how will we gather insights into the usage and performance (compliance to our Service Level Agreements (SLAs)) of our API assets as a big picture?
• How do we find and consider gaps in our API capabilities or opportunities to improve standards, performance, or processes across the organization?
• How do we gather or review inputs from API builders, consumers, or operators to see what they might need from our organization?

How Do I Answer These Questions, and What’s Next?

Putting together a governance team, selecting guidelines, reviewing tools, providing direction, and deciding what’s next is often best led by people with experience in the space. Most organizations that do software development will have API experts who can probably be brought together to help.

Typically a governance body will have representatives from IT, Security, Data Governance, business (product) and other key departments. Having the governance body take a service approach, considering education and guidelines over standards and mandates is usually more successful.

Consider bringing in some external help to set some of these things up, help kick start the initial sets of guidelines or standards, and certainly support API Management tooling development and integration. All of the above has to be considered in the context of your organization. While there are excellent best practices for API Governance and API Management patterns, usually you will want to adapt them to your specific needs and immediate challenges.

Solsys has consultants and expertise in these areas and has helped organizations explore these questions and API Governance. Sometimes just some initial guidance and direction can help, and we’d be pleased to discuss your challenges. Reach out to us on our contact form if you’d like to chat!

John has over 25 years of experience working in software and technology, with professional services consulting firms and product companies, ranging from large enterprises to small firms. John currently works with Solsys to help clients with their API governance, API management, and API security problems. Having spent several years as a Product Owner of an API gateway and management platform for a large telecom client in Canada, John is using hard-learned lessons from the front lines of a high-performance and high-volume API platform to enable clients to improve how they deal with their API technology.