The number of APIs created each year has absolutely exploded, partially due to AI and partially due to our decentralized and data-driven culture. API Evangelist Kin Lane estimates that large enterprises can have as many as 25,592, with two or more APIs for each employee. API governance is becoming increasingly mandatory, or you run the risk of your API ecosystem spiraling out of control.

API governance isn’t just about limiting the number of APIs in circulation, either. It’s an essential component of API-first design, where APIs are created directly from their API description.

Finally, API governance is one of the best ways to guarantee that your APIs are correctly formatted, so you can enforce standards on your APIs. Without making API governance seamless, however, it can become one more bottleneck for your team.

Quick Refresher: What Is API Governance?

API governance is the practice of officially defining policies, guidelines, standards, and processes for creating, designing, and implementing APIs. Proper API governance helps ensure consistency, security, communication, and cooperation between teams, helping you get the most out of your API portfolio.

5 Steps To Automate API Governance

API governance is as much about a change in mindset as it is about choosing the right tools and workflow. With the right design and implementation, nearly any API management platform can be used to automate API governance.

Below, we’ll walk through a step-by-step process to help you automate your API governance. We’ll showcase using an OpenAPI specification, creating rules with Spectral, and validating those rules within the development workflow.

1. Adopt OpenAPI

OpenAPI has become the default API specification for a great majority of API users, with over 63% of API developers preferring OpenAPI as their primary specification. A predictable, machine-readable API specification lets your automation tools know what to expect.

Using OpenAPI allows your APIs to be tested in automated testing environments, ensuring security and consistency. It also helps to automate API documentation generation or create SDKs for different programming languages.

2. Use An API Gateway

API gateways are an ideal location to automate your API governance, as it’s already part of your API development team’s workflow. This makes API gateways an ideal place to implement access management or rulesets for various API governance functions.

API gateways are a common element in distributed API environments, as well. Implementing API governance using an API gateway makes automated API governance available to anyone on your API team, no matter where they might be located. It also ensures that all API access is traceable, further enhancing everything from efficiency to API security.

3. Decide on Standards

Before you begin automating API governance in earnest, you should spend time making design decisions about your API. Will you be pluralizing resources in your API routing? Which response codes will you use? What will be your standard casing? You’ll want to make these decisions ahead of time, as they’ll inform every other stage of your API governance system.

It will also help you discover which decisions need to be made by actual humans and which can be handled by automation tools. To give you some ideas about the current best practices around API standards, definitions, and descriptions, you might spend some time browsing the API stylebook, which analyzes APIs from some of the biggest API producers in the world.

4. Set Up Automated Rules

Now, we’ll demonstrate how to set up your own rules so you can implement automated API governance yourself. For this example, we’re going to use the petstore.openapi.yaml file just to give you an idea of what these principles look like in practice.

To start, create a new directory for your project and then create the petstore.openapi.yaml file in your new directory.

For API governance, we’ll use Spectral, which is an open-source linter, to assess your API description and make sure it performs as well as it should. To install Spectral on your local machine, run the following command:

npm i -g @stoplight/spectral-cli

Once Spectral CLI is installed, Spectral can be run from the command line. Now you can use it on petstore.openapi.yaml with the following command:

spectral lint petstore.openapi.yaml

When you run the command, Spectral should inform you that a ruleset is needed to assess the YAML file. Now, let’s create a ruleset. Create a .json file named object-policies.spectral.json and implement the following:

{
    "description": "Object policies",
    "rules": {
        "object-policies:required-description": {
            "description": "Object must have a description",
            "message": "Object must have a description",
            "given": [
                "$..schemas[*]"
            ],
            "severity": "error",
            "then": {
                "field": "description",
                "function": "truthy"
            }
        }
    }
}

This lets Spectral know that every schema it encounters needs to include a description. This is a fantastic way to ensure that your API team is following your API governance protocols. Now, you can pass the ruleset to Spectral. Run the following command:

spectral lint petstore.openapi.yml --ruleset object-policies.spectral.json

API governance is meant to ensure that an API performs optimally. Now, let’s update the Object Policies JSON file so that it assesses whether or not an API follows a specified format.

{
    "description": "Object policies",
    "rules": {
        "object-policies:preferred-description-template": {
            "description": "Object description must implement template",
            "message": "Should contain 'A ... is a ... that ...' template",
            "given": [
                "$..schemas[*].description"
            ],
            "severity": "warn",
            "then": {
                "function": "pattern",
                "functionOptions": {
                    "match": "(A|An)\\s.+\\sis\\sa\\s.+\\sthat\\s.+"
                }
            }
        }
    }
}

With Spectral installed, you can write rules directly into your API description. Here’s an example of a naming convention written into the petstore.openapi.yaml file.

   extends: [spectral:oas]
    rules:
    adidas-paths-kebab-case:
    description: All endpoints/paths MUST follow kebab-case
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^/([a-z0-9]+(-[a-z0-9]+)*)?(/[a-z0-9]+(-[a-z0-9]+)*|/{.+})*$"

This rule asserts that all paths need to be written in kebab case. If you were to create an endpoint using camelCase, Spectral will let you know that a rule is broken.

5. Automate API Documentation

Let’s finish by showing you how to automate API documentation generation, as accurate API documentation is another important component of API governance as well. We’re going to use an open-source tool called Scalar to automate API documentation generation. To start, install Scalar by running the following code:

pip install scalar

Now, let’s create a simple Scalar boilerplate HTML file. Create an empty .html file and input the following:

<!doctype html>
<html>
<head>
  <title>My Scalar API Reference</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
</head>
<body>
  <div id="app"></div>
  <!-- Load Scalar -->
  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
  <!-- Initialize Scalar -->
  <script>
    Scalar.createApiReference('#app', {
      url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json',
      proxyUrl: 'https://proxy.scalar.com'
    })
  </script>
</body>
</html><!doctype html> <html> <head>  <title>API Reference via Scalar</title>  <meta charset="utf-8" />  <meta name="viewport" content="width=device-width, initial-scale=1" /> </head> <body>  <!-- Target container for Scalar -->  <div id="scalar-reference"></div>   <!-- Load Scalar library -->  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>   <!-- Initialize Scalar -->  <script>    Scalar.createApiReference('#scalar-reference', {      // Point to your OpenAPI specification URL (local or remote)      url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json', // Default example API      // Optional: Proxy URL for handling CORS in the built-in client      proxyUrl: 'https://proxy.scalar.com'    });  </script> </body> </html>

Save the file and open it in a web browser. You should see the documentation boilerplate at the localhost:8000.

Once that’s working, you can host your .yaml file using a simple HTTP server like python -m http.server or Flask, if you want to get more elaborate. Once you have a URL, you can insert that into the URL of Scalar.createApiReference. You should change proxyURL to null, too, as it won’t be needed.

After you’ve made these changes, save your HTML file again and then reload it. You should see your API documentation available as an interactive web page that’s guaranteed to be accurate and up-to-date.

Final Thoughts on Automating API Governance

API governance tools like Spectral can be run anywhere npm packages can be installed. It can easily be integrated into CI/CD pipelines like CircleCI. With proper planning, API design, and automation tools, automating API governance becomes built into your API workflow.

All this is particularly effective when paired with API testing, as the API governance ensures that your API descriptions follow the correct format before tests are run. Together, they create a robust pipeline for creating APIs and interactive API documentation with very little additional effort from your development team.