restful-checker 3.1.0

Check RESTful API compliance from OpenAPI definitions and generate HTML reports

RESTful API Checker

Validate RESTful best practices on your OpenAPI/Swagger specs. Generates HTML reports with actionable feedback.

This project is stable. Bug fixes will be released as issues are reported.

Installation

pip install restful-checker

Requires Python 3.8+

Usage

# Local file
restful-checker path/to/openapi.json

# Remote URL
restful-checker https://api.example.com/openapi.yaml --open

# Generate HTML + JSON
restful-checker openapi.json --output-format both --output-folder reports

Options

Option	Description	Default
--output-format	html, json, or both	html
--output-folder	Destination folder	./html
--open	Open HTML in browser	false
-q, --quiet	Suppress output	false
--version	Show version	-

What It Checks

URL Design

Check	Description
Versioning	Ensures /v1/, /v2/ appears early in paths
Resource Naming	Detects verbs in URIs, suggests pluralization
Resource Nesting	Validates patterns like /users/{id}/orders
Path Parameters	Verifies consistent {param} usage

HTTP Standards

Check	Description
HTTP Methods	Validates GET, POST, PUT, DELETE usage
Status Codes	Checks proper use of 200, 201, 400, 404, 409, etc.
Content Types	Verifies application/json usage
HTTPS Enforcement	Ensures all servers use HTTPS

Response Quality

Check	Description
Response Examples	Encourages example in responses
Error Format	Suggests structured code and message fields
Response Wrapping	Warns about unnecessary envelopes

Performance

Check	Description
Pagination	Suggests ?page= and ?limit= for collections
Query Filters	Recommends filters like ?status=
GZIP Support	Checks Accept-Encoding

Programmatic Usage

from restful_checker.engine.analyzer import analyze_api

result = analyze_api("path/to/openapi.json", output_dir="output")

print(f"HTML: {result['html_path']}")
print(f"JSON: {result['json_path']}")
print(f"Score: {result['json_report']['score']}")

Project Structure

restful_checker/
├── checks/         # Validation modules
├── engine/         # OpenAPI loader
├── report/         # HTML rendering
├── tools/          # CLI utilities
└── main.py         # Entrypoint

Contributing

Found a bug? Open an issue.

License

MIT

---