18 Automating API design guidelines
Designing APIs consistently is hard when teams must remember numerous naming, pagination, security, and modeling conventions. Automating these conventions with API linting brings those rules into the design workflow so issues are spotted early in the OpenAPI description, not late in development. Used as a companion to thoughtfully written guidelines, linting promotes consistency, usability, security, efficiency, and evolvability, while letting designers focus on meeting consumer needs rather than on clerical checks.
The chapter explains how to turn guidelines into executable checks, using a linter to scan OpenAPI documents for design and authoring issues. It highlights Spectral as a flexible choice: rules target elements with JSONPath (given) and validate them with functions (then), covering tasks like enforcing casing and optionality, ensuring presence or absence of responses and parameters, validating references to shared components, checking schema patterns with partial JSON Schema, and performing cross-element validations with custom functions. Clear, actionable feedback is emphasized through severities (error, warn, info, hint) and tailored messages so findings are meaningful, prioritized, and easy to fix.
Success hinges on deciding what to verify, keeping rules appropriately granular, and leveraging shared OpenAPI components to simplify checks. The chapter shows how to organize and share rulesets, factor common targets with aliases, version and evolve the rules, and let teams import, customize, and extend them per API while selectively ignoring acceptable exceptions. Integrated in IDEs, CLIs, and CI/CD pipelines, automated guidelines scale governance, reduce avoidable breaking changes, and make better API design faster and more reliable across varied API styles.
We can leverage an API linter to apply our guidelines seamlessly. Linting can help us with API design and OpenAPI authoring.
An API linter can detect API design and OpenAPI-related issues and help fix them with location indication and description.
Spectral rules target elements with given key (JSONPath) and check found values with then. It outputs failed checks as "problems."
Create Spectral rules based on principles and recipes' smaller statements to help detect and fix precise issues.
If the name and description don’t clearly convey what the rule checks or if they’re long and describe many checks, the rule doesn’t have the appropriate granularity.
Use the undefined function to see what the rule’s given finds. Test the rule on a valid OpenAPI document.
Use a.* and [a,b] to target all post and put operation responses objects with JSONPath.
Use a.*, ..b, and [?(conditions)] to get all query and path parameters with JSONPath.
Set the Spectral rule’s resolved flag to false to work on unresolved documents that still have their $ref elements.
Define Spectral aliases, which are reusable given values, under aliases and use them with #AliasName to prevent error-prone duplication of JSONPaths across different rules.
Blah
Combine field and defined function to ensure an element is present in an Object with Spectral.
Use the schema function and the contains JSON Schema keyword to ensure an element is present in an array with Spectral.
Leverage then.field and schema function to ensure a shared component is used in an object or an array.
Be mindful that when the value is a JSON Schema, the schema must be thought of as a JSON Schema of a JSON Schema!
To use a myFunction custom function, create a ./functions/myFunction.js file and add myFunction to the functions list in a Spectral ruleset.
The input argument is a value found by the given of the rule calling the function.
Add an object with a message and an optional path to the problems list to see it in the CLI output.
A helpful API linter lists meaningful problems, their location, their importance or nature, and how to solve them.
Always define a rule’s severity to consider the level of impact of the detected problems and guide how to react to them. Define the meaning of each level.
The message for a problem comes from the rule’s message or description or is the message returned by the function. The message field can contain {{placeholders}} (requires quoting).
The extends list imports other rulesets and Spectral built-in rulesets. Rules can be deactivated on import to activate only the needed ones. Imported rule severity can be overridden.
We can tweak our guidelines locally to adapt them to our needs and ignore non-fixable problems.
FAQ
What is API linting and why should I use it?
API linting analyzes an API description (for example, an OpenAPI file) with a linter to detect design and authoring issues and to automate your API guidelines. It helps you consistently apply patterns (naming, pagination, error handling, security), reduces avoidable mistakes, and lets you focus on meeting consumer needs. You can run it in an IDE, via CLI, or in CI/CD pipelines.How does Spectral lint an OpenAPI document?
Spectral evaluates each rule in three steps: 1) target elements with JSONPath viagiven, 2) check values with one or more then.function calls (e.g., casing, pattern, schema), and 3) report each failed check as a problem with location and severity.How do I decide which linting rules to create?
Base rules on your API guidelines to ensure each rule has a sourced purpose. Keep them right-sized: split broad concerns into small checks, use concise names and descriptions, and combine rules to cover a topic. Prefer leveraging shared OpenAPI components to simplify what rules must verify.How can I target elements in OpenAPI with Spectral?
Use JSONPath ingiven. Examples: $.paths.*[post,put].responses (POST/PUT responses), $..parameters[?(@.in === "query")] (all query params). Create reusable selectors with Spectral aliases (e.g., #AllParameters, or #CollectionResource.get for search operations) to avoid duplication.How do I check naming conventions or required flags?
Use core functions underthen: casing (e.g., camelCase names), pattern (regex), falsy/truthy (presence/boolean-like checks). Target subfields with field, and use @key to validate object property names.How can I ensure elements are present or absent?
For presence in objects, usedefined with then.field (e.g., ensure a "500" response exists). For arrays, use schema with JSON Schema’s contains and const to assert an item is included (e.g., a Correlation-Id header). Use undefined to ensure something is not present (e.g., no 404 on collection paths).How do I enforce use of shared OpenAPI components and references?
Setresolved: false in a rule to work with raw $ref values. Then use the schema function (with const/contains) to require references to specific shared components (e.g., standard 500 response or a Correlation-Id parameter). You can also check that schema bodies use $ref instead of inline schemas.Can Spectral perform cross-element checks?
Yes. Write custom JavaScript functions to compare distant parts, such as ensuring a creation request and response use the same read-write schema$ref. The function receives input (the matched element), options (functionOptions), and context (useful for paths and document access), and returns a list of problems.How do I provide helpful feedback and manage severity?
Useseverity to signal impact: error (MUST fix), warn (SHOULD fix), info (MAY improve), hint (investigate). Add clear, action-oriented messages via message and description; messages support placeholders like {{property}}, {{path}}, and {{error}}. Split rules if different checks need distinct severities or messages.How do I organize, share, and customize rules for a project?
Group rules into rulesets and import them withextends (including spectral:oas built-ins). Override severities or deactivate rules. Version your rulesets in a repo. In each API project, add a local .spectral.yaml to pull shared guidelines, add API-specific rules, toggle recommended: false rules, and ignore specific findings with overrides. Run via spectral lint or integrate in CI.
The Design of Web APIs, Second Edition ebook for free
