Use API Governance Tools for Better API Experiences
API governance is a cornerstone of good API experiences for both producers and consumers. We talk a lot about how OpenAPI is about much more than the tools, but the tools can help a lot, too. Let’s take a look at the options available and how they fit your workflow.
Tools for API Governance
The main tool in the API governance toolbox is the linter, sometimes also called a validator. These tools check an OpenAPI description against a set of standards. Which standards? The ones you configure. Investing the time to configure the linter to support the agreed API standards is a key ingredient to implementing good API governance.
There are multiple decent tools available for linting, and most of them are open source, which means you can easily try them out and find one you like. Try these for starters:
Each of these tools will offer a default “recommended” ruleset. However, these tend to be rather stringent, and I wouldn’t actually recommend them as a starting point unless they align closely with the API standards you identified for yourselves. Especially when retrofitting API governance to an existing API project, slow and iterative is the real recommended approach.
Start Simple
Start by picking a tool: in these examples, I’m using Vacuum, but Spectral supports the same rule configuration if you prefer that. Turn off the default rules and enable what makes sense for your situation. A great place to start is to enable the oas3-schema rule and check that the OpenAPI description you have is valid. It’s surprising how many OpenAPI tools don’t quite output valid OpenAPI in every situation.
To turn off the default rules and check for a valid description, use a ruleset.yaml file like this:
Run this ruleset over your openapi.yaml file with Vacuum using the following command:
|
1 |
vacuum lint --details --ruleset ruleset.yaml openapi.yaml |
If you don’t have an OpenAPI file handy, you’re welcome to grab the Blog OpenAPI example I used and try that. (It includes some problems that will be exposed when we add a few more rules.)
If the OpenAPI description is invalid, the problems and where in the file they occur will be displayed in the output. The command also returns an error, so this tool is useful in a CI setup, where it will return a failure status and alert you of a problem.
Selectively Add Rules
One reason why the recommended rulesets are such a challenge for existing APIs is that they don’t have the context of what your application does and what’s important. It’s better to focus on the areas that matter to your organization instead of a generic set of priorities.
In this example, the focus is on developer experience, creating an API that our technical users will be happy to integrate with. To support this, the first rules to add are:
operation-operationIdandoperation-operationId-uniquemake sure that each operation has a unique identifier; these values are used as anchors in documentation and often as method names in generated SDKs.operation-tag-definedandtag-descriptionrequire every tag used in the API description to be declared in the top-leveltagssection and to have a description.operation-description,schema-description, andcomponent-descriptionensure that there are description fields throughout the API description. Adding meaningful information, written by humans, is low-hanging fruit when it comes to improving the developer experience of your API.description-duplicationprovides a low-level information message if two description fields are identical, as this usually indicates a copy/paste error.
With the additional rules, here is the updated ruleset.yaml file:
You might notice that when we run the command this time, the output reports some problems:
Vacuum’s output reports errors.
The errors are caused by one of the endpoints missing both an operationId (technically not a required field in OpenAPI but definitely a good idea) and a description. Try fixing the error yourself and rerunning the command to see the updated output.
For your own API descriptions, pick the rules that fit the priorities you have. Dig into the Vacuum rulesets documentation and build out a starter set of rules to fit your own project.
Integrate Checks Into Your Workflow
Having API linting running at multiple points in the API development lifecycle is good practice because it keeps the feedback cycles short and helps developers innovate faster.
For design-first projects, having linting set up on local development platforms is a must-have. Some tools integrate into IDEs, or you can run the tools on the CLI on your development machine.
Whether designed or generated, OpenAPI changes should be reviewed in a pull request, and API governance checks including linting definitely belong there! Use the CLI command from above in your existing CI workflow setup, such as GitHub Actions or GitLab/Azure pipelines.
Vacuum can produce an interactive HTML report that is a very user-friendly way to review the output of the linting rules. Use it locally for a nicer way to see what’s happening, or build it in your CI process to give reviewers a pleasing interface to look at. Vacuum’s support for documentation for every rule (including any custom rules you create) is a great way to provide more context and advice to support each rule.
Vacuum’s dashboard provides interactive reports.
You might also want to look at the dashboard command, which produces a terminal-based dashboard of linting output, or generate a report in JSON or Spectral format.
API Governance Is More Than Automation
API governance is more than automation, but automating the easy stuff really helps. Don’t feel daunted by the long lists of things that aren’t perfect or rules that aren’t enabled.
Adding linting to your day-to-day work brings quality and consistency to your API development, and even if there are things you can’t fix today, the checks can be added to avoid any regressions or mistakes in new API features as it grows.
So look at where you are with API governance, and where you’d like to go, and use linting to help you take a step or two along the way.
