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:
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-operationId` and `operation-operationId-unique` make 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-defined` and `tag-description` require every tag used in the API description to be declared in the top-level `tags` section and to have a description.
- `operation-description`, `schema-description`, and `component-description` ensure 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-duplication` provides 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:
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.
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.
Hasura makes data access easy, by instantly composing a GraphQL API that is backed by databases and services so that the developer team (or API consumers) get immediately productive. The nature of GraphQL itself and Hasura’s dynamic approach makes integration and iteration easy.
