API linting is the process of making sure that APIs are not just technically correct (which is the realm of validation tooling), but that they also comply with a set of additional constraints that often are documented in the form of API guidelines.
With the growing popularity of APIs, these guidelines become more common, APIs throughout organizations become more abundant, and it thus becomes more important to be able to scale the API practice in organizations. API linting can help with this because it allows you to check and enforce (some aspects of) API guidelines, making it easier for API teams to follow guidelines and making it easier for API platform teams to make sure that guidelines are being followed.
In this interview, Stoplight’s Phil Sturgeon talks about Spectral. Spectral is an open-source general-purpose JSON/YAML linter, but it does come with built-in support for API-related formats such as OpenAPI, AsyncAPI, and JSON Schema. We discuss why Spectral is useful and what Spectral can do to help with managing APIs and API landscapes.
Why Spectral?
Looking at the general trend to expose APIs and use them as the fundamental building blocks of digitalization, it becomes obvious that scaling the API practice is critical. The ability to scale the API practice often becomes a critical challenge after it has been decided that APIs should become an important strategic direction.
What does Spectral do?
Spectral allows automating some of the constraints that typically are part of API guidelines. It accepts rules that will be applied to OpenAPI or AsyncAPI descriptions of APIs. API teams can then use Spectral to check whether their APIs follow the given rules.
Spectral rules will not be able to capture all the constraints that are typical for API guidelines, but it’s a good starting point to be able to at least partially automate the process of checking APIs against API guidelines.
Two important aspects of most API strategies are to allow for some autonomy of API teams and to use APIs as a way to increase the velocity with which new capabilities can be delivered.
- Autonomy can be increased because the easier it is to check for compliance with API guidelines, the easier it becomes for teams to create and change APIs without having to be concerned about running into compliance issues later on.
- Velocity can be increased because API reviews can be partly automated, meaning that issues can be caught earlier on and are easier to fix. It also means that the potential bottleneck of API reviews performed by an API platform teams can be managed in a more effective way, by using manual review processes only for those parts that cannot be automated.
Another interesting aspect about Spectral is that it comes with a set of default rules, which already can provide some useful feedback about the quality of API descriptions.
These default rules can be augmented over time to also include specific rules for an organization. It is indeed highly likely that rules will be modified and added over time. This would be a natural development given that the API design practices in an organization also evolve over time.
Spectral Details
The following interview with Phil Sturgeon discusses the questions of API guidelines, the motivation for Spectral as a tool, and the general idea of what it does in more detail. If you are interested in more information about Spectral, Stoplight has a dedicated page for Spectral, and there also is the GitHub repo with the source and documentation.
If you liked this video, why don’t you check out Erik’s YouTube channel for more “Getting APIs to Work” content?