How AI is Levelling the API Governance Playing Field
‘API governance’ can sound like an intimidating concept. When I started as a solutions engineer at SmartBear in 2018, it took me a while to wrap my head around what exactly API governance entails and even longer to be able to explain it clearly and simply to our customers.
The good news is that it’s not as complicated as it sounds: think of API governance as scalable quality checks that make sure you aren’t shipping APIs that break other components in your system, render documentation obsolete or that don’t comply with your industry’s laws and regulations. When you think about it this way, API governance transforms from some abstract target into something you can work on and influence in your daily work, regardless of what stage of the development lifecycle you’re contributing to.
A Fancy Name for Linting?
In the Swagger ecosystem, the smallest building block of API governance is good old-fashioned linting. A linter is a formatter with syntax rules that scans your code (in this case, your API designs which are usually JSON or YAML files) and notifies you if you’ve made any mistakes in how the file is written or structured. For example, Swagger Editor has a built-in linter that will tell you if your API definition does not follow all the rules of the OpenAPI Specification.
So far, so good. But I mentioned earlier that API governance should be scalable. That’s where Swagger Studio (formerly SwaggerHub/API Hub for Design) comes in. Not only is it a hosted version of Swagger Editor, but it also includes the ability to create and store a centralized repository of linting rules that can be applied to all the APIs that you store in Swagger Studio. While Swagger Editor only checks to see if your API is following all the OpenAPI Specification rules, Swagger Studio lets you create custom rules to check things that might be specific to your team or industry. This means that API designers don’t have to all keep a personal copy of their favourite style guidelines. Swagger Studio keeps them all in one place and applies them to all your APIs even as you’re designing them.
How Can AI Help?
The tooling that underpins the custom rules feature in Swagger Studio is Spectral, the most popular open-source linter for APIs. A Spectral ruleset is a JSON, YAML, or JavaScript/TypeScript file (often the file is called .spectral.yaml for a YAML ruleset) that contains a collection of rules, which can be used to lint other JSON or YAML files such as an API description.
Spectral has been a topic of conversation for me since 2018. When I used to suggest that teams should start using it, the most common objection was similar to objections that I heard about using OpenAPI more generally; we don’t have time to learn this new language/syntax/process. Given how stretched the modern software team is, this shouldn’t be surprising.
The good news is that the advent of AI assistants is dramatically reducing the effort required to get the most out of this fundamental building block of API governance. For example, Swagger Studio now supports prompt-generated Spectral rules. This means that an API stakeholder who has expertise in the business or regulatory domain that the API will be used in, but who perhaps isn’t fluent in JSON or YAML, can still contribute to their team’s API guidelines.
When you combine this with Swagger Studio’s support for AI-assisted API design, you’ve got a tool that removes complexity rather than introduces it unnecessarily.
As a solutions engineer, I gave countless demos. Sometimes the audience would be more on the technical side of the house (developers, testers, engineers) and sometimes they’d be closer to the business (analysts, technical writers, project managers). Swagger Studio’s AI assistants are aimed at the latter group as a way of allowing them to contribute their domain expertise to API design. For the former group, who aren’t as concerned about the effort involved in writing up a few custom JSON or YAML files, the focus is more on how Swagger integrates with their automation frameworks and CI/CD pipelines so that they can leverage API governance in their build pipelines to catch non-compliant APIs before they make it into production. If that sounds interesting, be sure to register for a deep dive on how to use Swagger in your DevOps workflows on November 11th. Until next time!