When teams invent their own API conventions, consumers must learn inconsistent patterns across APIs. An API style guide is a shared reference for the design conventions teams must follow. It can specify naming conventions, pagination patterns, error formats, paths, authentication, and security guidance. Consistency supports API usability and adoption; a guide gives designers and reviewers a common standard. section 1.7 section 3.1 section 10.0
Put the guide to work during API design:
- Document conventions clearly enough for designers to apply them. An organization without a guide can adapt a publicly available one rather than start with a blank page. section 3.1
- Turn checkable guidelines into executable rules. Run an API linter against API definition files in an editor or on the command line, then repeat the check in CI for fast feedback. section 1.5.3 section 3.1
- Use a separate comparison tool or script for requirements such as detecting breaking changes between definition versions. Do not assume a static linter can check every guideline. section 1.5.3
- Decide which findings should fail the build. Distinguish mandatory from optional guidance; MUST, MUST NOT, and SHOULD can help map guidelines to ERROR, WARN, or HINT levels. section 8.11.4
From convention to check
Suppose a guide requires CamelCase URI paths, OAuth2 authentication, and error responses containing a message and identifier code. Those are design rules, not merely reminders. A Spectral ruleset can execute suitable checks against an OpenAPI definition; a Spectral rule identifies the elements to inspect with a JSONPath expression and specifies a function to check them. If a built-in function cannot express a requirement, a custom function may be needed. Review each reported problem against the guideline and its assigned severity before deciding whether the design or the rule needs adjustment. section 3.1 section 3.12 section 10.0 section 8.11.4
Automation does not replace design review. Reviewers still need to assess questions a rule cannot settle, such as whether a resource model and its names make sense to consumers. Reviews can also expose new patterns, ambiguous guidance, or gaps that should be discussed and reflected in the guide and its lint rules. Make the guide available early, before a proposed design reaches review; rerun compliance checks whenever the definition changes. section 1.7 section 5.2.6 section 5.3.3 section 1.5.3
