Next time you’re in a group of API enthusiasts, ask the following question: “Is API governance a good thing?” The response will, with the occasional API libertarian as a possible exception (“Don’t tread on my endpoints!”), almost universally be yes. At least when it’s done well.

In a recent post on reasons why you need API governance, we covered some of its tangible advantages — namely that it improves security, reduces sprawl, and encourages adoption. All good things if you’re looking to keep your APIs in check.

Now, ask that same group: “What is API governance?” Once the “umm”s and “well”s subside, you might be left with either silence or a mixed bag of vague responses. That’s because API governance as a concept isn’t always particularly well-defined.

In this post, we’ll look at a few key tenets of API governance and break down exactly what it encompasses. So, if someone should ask you exactly what API governance is, you’ll be ready.

APIs and Their Governance in Context

Merriam-Webster defines governance as “the act or process of governing or overseeing the control and direction of something (such as a country or an organization).”

Right off the bat, there’s an obvious problem in applying this definition to APIs: there’s no universal governing body or council of elders that dictates what we’re allowed to do with APIs. That guidance will likely come internally via project managers or centers of excellence.

But there’s no single way to document or define any given API. Granted, standards like the OpenAPI Specification and TypeSpec have emerged organically, but their enforcement isn’t enshrined in law before we can call something an API.

As a result, attempting to reach a consensus on how APIs are used within an organization can be extremely difficult, especially when many team members may not even know what APIs are available or understand how they can use them within their workflows.

What an API looks like can also vary massively by type, including SOAP, REST, or GraphQL. They also change by the intended scope of use, such as public, private, partner, or composite. This begs the question, should we simply give up on API governance? (Spoiler alert: no.)

Emerging Standards in the API Space

In a 2020 Forbes article, Mark Settle wrote the following:

“Most organizations have made significant investments in API integration skills and tools. However, the ways in which API architectures are managed varies widely. Very few companies have developed the organizational structures, processes and discipline required to turn their API business architectures into a source of competitive business advantage.”

Four years on, that’s not quite as true as it was back then. More and more businesses are demonstrating a desire to engage with APIs. According to Postman’s 2024 State of the API Report, 74% of developers adopt an API-first approach. The report also found that close to 50% of organizations have a central team that “oversees API strategy and governance.”

On the technical side, as opposed to the organizational side, we’ve seen widespread adoption of standards like OAuth 2.0 and the OpenAPI Specification. Regarding the architectural style, Alex Xu wrote in 2023 that 86% of APIs used REST as their architectural style, down from 92% in 2021 due to the rise of challengers, but still a dominant showing.

It could be argued that the emergence of best practices within the industry and their subsequent adoption by large numbers of API developers has created a de facto status quo that can simplify the path toward effective API governance. But we can’t just stop there.

5 Key Tenets of API Governance

Despite some of the difficulties associated with standardizing the production of APIs, the industry’s willingness to embrace open standards and best practices has helped to shape our view of APIs. On its own, however, that isn’t enough to be considered API governance.

So, let’s try to nail down something closer to a useful definition:

“API governance consists of all attempts made by a company to actively shape how APIs are developed, defined, secured, and deployed by employees and partners of the organization.”

Here are five aspects that API governance strives to enforce, which you should consider to maximize its success.

1. Discoverability

Providing a way to search for deployed APIs is a vital part of effective governance. The aforementioned Postman report found that 43% of developers rely on their colleagues to explain APIs. And that doesn’t even cover other teams — marketing, sales, support — who could make good use of APIs but don’t know where to look. This could mean creating a dedicated portal for published APIs to ensure that all relevant stakeholders can get the information they need.

2. Usability

Following on from the above, APIs should be well-documented. Excellent documentation has “quick start” tips, endpoint definitions, code snippets, and more information to aid developer experience, readily available alongside your APIs.

The same Postman report mentioned above found that 44% of respondents rely on chat tools or email threads to inform API development and consumption within their organization. While it’s always nice to see collaboration, that statistic speaks to the fact that many companies could benefit from expanding the scope of their documentation and troubleshooting guides.

3. Consistency

In her 2023 Platform Summit talk on improving developer experience with support resources, Microsoft’s Kristen Womack refers to the Similar Hallways model. She argues that presenting content “in a way that feels familiar to people who are working across them is helpful so they know they’re not lost” but that “you can still have a unique flavor to what you’re doing.”

Encouraging consistency is a desired outcome of governance. If one of your APIs uses the OpenAPI Specification, it makes sense to use it for others as well. Likewise, you should aim to showcase code samples and example responses in similar places across all documentation.

4. Security

API governance and security go hand in hand since many processes involved with the former dictate the actions taken when you have, say, data breaches or periods of unscheduled downtime. (We hope it goes without saying just how important API security is!)

If your organization deals with sensitive data or is required to comply with legislation like GDPR or CCPA, that should form part of your governance strategy, too. How data is accessed and transmitted, for example, and how long you’re storing it for (if you’re storing it at all).

5. Versioning and Deprecation

While it may not sound all that compelling or fun, housekeeping tasks are also part of API governance. And that includes effective lifecycle management like versioning, deprecation, and retirement.

Streamlining your offerings — ensuring you’re actively promoting upcoming changes, updates, and so on — demonstrates your desire to create an effective ecosystem and that you’re committed to engaging with the community around your APIs.

Atlassian, for example, maintains a set of Extensibility Standards that are enforced automatically as part of their approach to API governance. It’s easy to imagine how such a system could be applied to existing APIs in the context of change management.

API Governance is Always Changing

In a great post on API Evangelist, Kin Lane highlights that API governance is an evolving concept. “I should know what API governance is, but I know enough to know that this definition is fluid and changes over time.”

Consider, for example, the rise of artificial intelligence. At our 2024 Austin Summit, Paul Dumas argued that “AI itself is going to become an API consumer. AI tools are going to be looking into APIs and executing them, and invoking them to get data and information to build their models with.” That will place additional emphasis on ensuring that API documentation is machine-readable.

But it won’t be the only area of impact. We’ll also need to ensure that any generative AI output to be used in the production or documentation of APIs is reviewed thoroughly for consistency and compliance and to validate it works in the context of existing workflows. More governance.

In a TechRadar article, Salt Security’s Eric Schwake wrote about how any organization looking to use generative AI with APIs “must adopt robust API management strategies, including comprehensive visibility, discovery, governance, threat detection, and mitigation of all APIs.”

Changes to legislation, wider adoption of generative AI, and other technological advancements all mean that API governance isn’t something you do once but an ongoing and iterative process.

Everybody Needs to Embrace API Governance

As it stands, the advantages of API governance that work properly should be fairly obvious. But it’s worth highlighting how the areas of focus outlined above come together to reinforce a cyclical pattern of adoption and engagement within an organization.

When APIs are discoverable, they’re more likely to be used by stakeholders. If they’re well-documented, they’re easier to deploy. Consumers are more likely to turn to your other APIs when their deployment maintains a consistent feel. If they’re secure, users are more confident trusting their output and integrating them into other services. Rinse and repeat.

Although one person might be tasked with overseeing API governance within an organization, we can see from everything above that effective governance is a team sport. It requires input from, and buy-in from, many different teams. It needs to work for everybody, or it may end up being ignored.

When nobody adheres to it, an API governance strategy is just a big jumble of words. It’s never too early or too late to get your team together and ask the big question: “What is API governance?” Or, perhaps in the spirit of collaboration, “What does API governance mean to us?”