API design principles checked in CI
Lint OpenAPI specs against 32 RFC, pagination, idempotency, and OWASP rules.
Zero external dependencies in Python 3.9+ or right here in your browser.
Validate an OpenAPI spec
Paste JSON or YAML below, load a preset spec, and export a Markdown or JSON violation report.
| Severity | Rule | Location | Violation and fix | Standard |
|---|---|---|---|---|
| Select Validate OpenAPI Spec to run all 22 automated checks. | ||||
Run in CLI, GitHub Actions, and diff checks
Switch workflows to enforce team presets, block breaking changes, and upload SARIF 2.1.0 alerts.
python3 api_validator.py --spec examples/orders-api-good.openapi.yaml --preset strict-public-api python3 api_validator.py --spec "services/*/openapi.*" --format markdown --output reports/api-lint.md
Runs on Python 3.9+ standard library only with zero pip dependencies for both JSON and YAML OpenAPI specs.
python3 api_validator.py --diff openapi.base.yaml openapi.head.yaml --format markdown
Flags removed endpoints, newly required fields, property type changes, and narrowed enums before merge.
uses: api-design-tools/api-design-principles@v1 with: spec: "services/**/openapi.yaml" preset: "stripe-style" diff-base: "openapi.base.yaml" fail-on: "error" write-summary: "true"
Appends a rule-violation table directly to the GitHub Actions Step Summary on every Pull Request.
python3 api_validator.py --spec openapi.json --preset owasp-api-top10 --format sarif --output api-lint.sarif
Built-in presets in presets/: google-aip, stripe-style, owasp-api-top10, and strict-public-api.
32 API design principles
Filter the complete ruleset by RFC standard, category, or enforcement mode.
| Rule | Mode | Principle and standard | Bad example | Good example |
|---|
Topic guides and comparisons
Reference guides for every rule family and protocol choice.