API linting with Spectral: from the basics to enterprise-wide automation

Spectral is an open-source API linting tool that allows users to write rules which then can be used to check API descriptions. Its functionality is a key integration in our Amplify Engage (formerly Enterprise Marketplace) platform, allowing teams to automate validation for APIs they can trust.

At its core, Spectral is very simple: you input an API description (OpenAPI, AsyncAPI, Swagger…) and a set of rules, and then Spectral checks whether the API description follows the rules.

In this blog, we’ll explain how Spectral helps perform API linting, and how you can use it in Amplify Engage to perform an increasingly powerful set of API governance tasks.

Amplify Engage: Unify Distributed APIs

How API linting with Spectral works

Spectral (powered by Stoplight) allows you to automate some of the constraints that are typically 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.

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.

How to use Spectral to level up your API governance

Let’s dig a little deeper into how Spectral can be used for an increasingly powerful set of tasks.

This means you can start making Spectral part of Amplify Engage and your API governance strategy with very little effort, then level up the way you’re using it over time.

Here are 7 steps for taking API linting with Spectral from a simple out-of-the-box tool to one that can level up your API governance:

1. Out of the box. Spectral comes with built-in rules that go beyond what the API specifications require. This means that you can use Spectral out of the box without adding any rules yourself. You then get the result of checking API descriptions per Spectral’s default rules, and that can already catch some issues with API descriptions.

spectral lint examples/petstore-openapi-scenario-1.yaml

2. Create/extend rulesets. Many users want to change and/or add rules, and for this Spectral allows to specify additional rulesets. Using Spectral this way now allows you to specify additional rulesets that Spectral will use to check your API descriptions.

spectral lint --ruleset rulesets/petstore-scenario-2.yaml examples/petstore-openapi-scenario-2.yaml

3. Turning off rules. Some rules in rulesets that you are using may not be to your liking. For this case, Spectral supports selectively switching off certain rules. This means that you can use an existing ruleset without changing it, but you can still control how it’s used by switching off certain rules.

extends:
  - ./petstore-scenario-2.yaml
rules:
  operation-description: off
  oas3-unused-components-schema: off

4. Built-in functions. Spectral has several built-in functions you can use to implement rules yourself. These functions allow you to perform operations and will return success or failure results.

In this example, we’re using a regular expression function for matching a string against a regular expression.

extends:
  - ./petstore-scenario-3.yaml
rules:
  hyphen-delimited-uris:
    message: "Words in the path must be lowercase and delimited by a hyphen or concatenated, or be a path parameter"
    severity: error
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(?:\/(?:[a-z]+(?:-[a-z]+|)+|\\{[a-zA-Z]+\\}))+$"

5. Custom functions. If what you want to check in a rule is not covered by Spectral’s features or built-in functions, you can write your own functions (which must be implemented using JavaScript). You can then use these custom functions in rules in the same way as built-in functions.

extends:
  - ./petstore-scenario-4.yaml
functions: [responses]
rules:
  operation-2xx-response: off
  default-response-fallback:
    message: "Response object does not have 2xx operation or default set"
    given: "$.paths.[*].[*].responses"
    severity: error
    then:
      function: responses

6. Organization-level rulesets. Moving on from using Spectral individually, the next step is to manage rulesets so that they are organized to be applied by different teams, and possibly for different types of APIs (e.g., private/partner/public) or for different maturity stages of APIs (e.g., prototype vs. publicly available).

This is where Spectral becomes a powerful tool for API governance, making it possible for an organization to encode and check guidelines in a way that can be incorporated into development processes.

See also: The role of API standards in an enterprise strategy

7. Automating API linting. Building on the previous point, the last point now is to make Spectral checks part of your development pipelines, meaning that checks will be done automatically every time you make changes to the API descriptions.

Because Amplify Engage (formerly Enterprise Marketplace) serves as a single point of truth for all APIs an organization exposes, you can leverage its automated API discovery across all your gateways to centralize and automate this API linting process.

Dive deeper into how Amplify Engage helps automate your API governance here.

This means that there is no time-consuming manual review process, and teams get alerted of problems with the API descriptions as quickly as possible.

Getting started with API linting is as simple as installing Spectral, and all other steps then can be done when necessary. For more details, watch this video where API experts Chris Wood and Erik Wilde walk you through all the steps.

>>Click here for the code from the GitHub demo repository.<<

In conclusion, Amplify Engage allows API teams to gain valuable insights automatically upon service discovery. Checking whether APIs are compliant with governance rules has never been so easy – especially with growing complexity in the API landscape, any quick insights are meaningful.