Improve the Quality of Your APIs with Spectral Linting

Spectral is an open source linting tool for APIs, specifically those described using the OpenAPI specification (formerly known as Swagger) and API definitions, developed by Stoplight. It is designed to help developers create, document and maintain APIs that are easy to use and understand.

The tool is a linter that can be used to enforce rules and standards on JSON and JSON Schema documents. Spectral can be used to lint APIs by checking the structure and content of the API’s request and response payloads, as well as the structure and content of the API’s documentation, such as OpenAPI, AsyncAPI or RAML (RESTful API Modeling Language) documents.

How Linting Improves APIs

API linting offers a lot of benefits in managing your APIs, such as:

Consistency: Linting can help ensure that your API is consistently formatted and follows a set of established best practices, making it easier for developers to understand and use your API, and reducing the chance of mistakes and misunderstandings.

Maintainability: Linting can help identify potential issues with your API that could make it difficult to maintain in the future. For example, it can detect the use of deprecated or otherwise unsupported features, enabling you to address and fix them before they become a problem.

Reliability: Making sure your API functions optimally is key to its success, and that’s where linting comes in. It can help you identify and fix performance problems, such as improving the response times of your API. In short, linting can ensure the reliability of your API.

Security: Using linting tools, you can detect potential security flaws in your API, such as the absence of authentication and authorization checks. By doing so, you can protect your API and the data it handles from possible risks.

Gaining Insight into APIs

To use Spectral to lint an API, you will need to define a set of rules that the linter should enforce. These rules can be specified in a configuration file or passed as command-line arguments when running the linter.

Once you have your rules configured, you can use Spectral to lint your API by running the linter on the relevant JSON or JSON Schema files, or on the OpenAPI, AsyncAPI or RAML document that defines your API. Spectral will then check the documents against the rules you have defined and report any violations it discovers.

For example, you might use Spectral to ensure that all API responses include a consistent set of headers, or that all API requests include a required parameter. You could also use it to enforce naming conventions or enforce a specific style for your API documentation.

Why Spectral Is Popular for API Linting

Spectral is a popular linting tool for API design due to its customizability, comprehensive set of built-in rules, easy integration and community support. With Spectral, you can write your own custom rules to enforce your own conventions and best practices.

Its built-in rules cover a wide range of best practices, from security and performance to usability. Additionally, Spectral is easy to integrate into your development workflow, making it an ideal choice for CI/CD pipelines, code editors, and integrated development environments (IDEs).

Thanks to the open source nature of the project, you can get help and support from the community if you ever have any questions or issues.

Use Spectral to Lint an API Specification

You can use Spectral to link an API spec from the command line. First, you’ll need to have Spectral installed on your system. You can install Spectral using npm by running the following command:

(Let’s assume you are using npm as your package manager.)

Once Spectral is installed, you can use the spectral lint command to lint your API. The basic syntax for this command is:

In this example, “files” is a list of one or more JSON or JSON Schema files, or OpenAPI or AsyncAPI or RAML documents, that you want to lint.

You can use various options to configure the linting process. For example, you can use the --ruleset option to specify a specific set of rules to use, or the --format option to specify the output format for the linting results.

Once you have fixed any linting errors, you will need to re-run Spectral to verify that your API definition passes the linting process. This process should be repeated until the linting process passes without any errors or warnings.

To ensure that your API definition meets the standards specified by Spectral, you may need to edit the API definition file accordingly. For more information on the available options and the Spectral lint command, please refer to the Spectral documentation.

Level up Your Event-Oriented APIs

In the context of event-oriented APIs, Spectral linting can be used to ensure that the API is designed in a way that makes it easy for developers to create, consume and process events. This might involve establishing guidelines for how events should be named, structured and documented, and how the API should handle them.

Some examples of rules that might be used in Spectral linting for event-oriented APIs include:

• Ensuring that events have clear, descriptive names that accurately reflect their purpose and content.
• Ensuring that events are structured in a way that makes them easy to process and understand.
• Ensuring that events are well-documented, with clear descriptions of their purpose, structure and any other relevant information.
• Establishing guidelines for how events should be handled by the API, including when they should be triggered and how they should be processed.

Custom Rules and Rulesets

Spectral comes with two rulesets: OpenAPI and AsyncAPI. But you can customize and create a ruleset that fits your project or organization. This can help you and your team create better APIs, as well as improve API design and API development processes.

There are several built-in rulesets that you can use with Spectral, or you can create your own custom ruleset by defining a set of rules using the Spectral rule syntax. Here are some examples of oas “OpenAPI specification” built-in Spectral rulesets:

oas2-recommended: This ruleset includes a set of recommended best practices for designing and documenting APIs using the OpenAPI 2.0 specification.

oas3-recommended: This ruleset includes a set of recommended best practices for designing and documenting APIs using the OpenAPI 3.0 specification.

oas3-security: This ruleset includes a set of rules for validating the security definitions and security requirements of an API defined using the OpenAPI 3.0 specification.

oas3-parameters: This ruleset includes a set of rules for validating the parameters of an API defined using the OpenAPI 3.0 specification.

To use a Spectral ruleset, you can specify it as an option when running Spectral. For example:

You can also combine multiple rulesets by specifying them as a comma-separated list. For example:

You can also include your custom ruleset as part of a larger ruleset by using the extends field. For example:

This custom ruleset extends the oas3-recommended ruleset and adds two additional rules. When this ruleset is used with Spectral, it will include all of the rules from the oas3-recommended ruleset as well as the two custom rules defined in the rules field.

It’s also possible to create custom rulesets in Spectral linting by defining a set of rules in a separate configuration file and then including that file in the main Spectral configuration file. This can be useful if you have a large number of rules and want to organize them into separate files for easier management.

Detecting Errors in a CI/CD Workflow

To make the linting process more efficient, you can integrate Spectral into your workflow by running it automatically as part of your build process or continuous integration pipeline.

To ensure your OpenAPI specification is up to date, you can set up your CI/CD pipeline to fail if Spectral returns any errors, or allow warnings but fail if there are errors. Additionally, you can integrate Spectral into your code editor or IDE to get real-time feedback as you write your OpenAPI specification.

To fail a Spectral linting check in a CI/CD pipeline, you need to add a step to check the exit code of the Spectral linting command and fail the build if necessary. Depending on the specific CI/CD pipeline you are using, you may need to use a tool or plugin specific to your CI/CD pipeline to handle the linting errors and fail the build if necessary.

For example, in a Jenkins pipeline, you could use the “error” step to fail the build if there are linting errors.

Overall, the approach to fail a Spectral linting check in a CI/CD pipeline will depend on the tools and plugins available to you, but the key is to find a way to check the exit code and fail the build if necessary. This way, you can ensure your OpenAPI specification is always up to standards before it is deployed.

Establishing Organizational Rules

Organization-level rule sets in Spectral provide a way to define and share linting rules across multiple API projects within an organization. By creating a configuration file with the rules key, you can specify which rules should be enabled or disabled.

It is also possible to use the extends key to specify a base rule set, and then override specific rules in that set using the rules key. This makes it easier to maintain consistency in linting rules across an organization, ensuring that all API projects adhere to the same standards.

For example, the following configuration file defines an organization-level rule set that extends the OAS3 rule set and disables the operation-tags-alphabetical rule:

Once you have defined your organization-level rule set, you can share it with your team members by providing them with a copy of the configuration file or by storing it in a central location that is accessible to everyone.

To use the organization-level rule set, team members can specify it as the base rule set when linting their API projects. For example, they could add the following to their project-level Spectral configuration file:

The Benefits of API Linting for Design, Governance

Improve the quality and consistency of your API. By linting your API definition, you can catch potential issues or inconsistencies before they become a problem. This can help to improve the overall quality and consistency of your API.

Enforce best practices and standards. By using a set of rules or standards when linting your API, you can ensure that your API follows best practices and adheres to industry standards. This can help to make your API more predictable and easier for developers to use.

Automate testing and validation. API linting can help to automate the testing and validation process, allowing you to catch issues early on in the development process. This can save time and effort and help to ensure that your API is ready for production.

Improve documentation quality. By linting your API documentation, you can ensure that it is accurate, complete, and up-to-date.

Conclusion

Spectral is an essential tool for any API developer, as it helps to ensure that the API is secure and reliable and that the data it handles is of high quality. It is also very easy to use and can be used to quickly identify any potential problems with the API. Additionally, it can be used to generate client code and to test the API manually to make sure that it behaves as expected.

Overall, Spectral linting is an invaluable tool for any developer looking to create an OpenAPI document that is secure, of high quality, and reliable. It is an important part of the process of creating and maintaining an OpenAPI document and will help to ensure that the API is a success.

Robert is a systems engineer and open source advocate who loves sharing knowledge. He believes in helping others and is compassionate about giving back to the community. When he’s not geeking with Linux he likes hiking, mountain biking, and exploring...

Read more from Robert Kimani