skills.rest
BryanPinheiro77
BryanPinheiro77COMMUNITY
Explore all skills by this author →
GitHub

api-design-reviewer

Lints OpenAPI specifications, detects breaking changes, and scores REST API design quality.

2|Updated Mar 24, 2026
Search Tags:#linting#api design#openapi#rest#breaking changes#swagger#api review
One-click install
npx skills add https://github.com/BryanPinheiro77/FinanceBot-BackEnd --skill api-design-reviewer-bryanpinheiro77
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-reviewer
Source: https://github.com/BryanPinheiro77/FinanceBot-BackEnd/tree/main/.agents/skills/api-design-reviewer
Command: npx skills add https://github.com/BryanPinheiro77/FinanceBot-BackEnd --skill api-design-reviewer-bryanpinheiro77

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Inconsistent naming, missing versioning, and undocumented breaking changes slip into APIs during development and only surface after clients break. This Skill automates REST API design review so convention violations, breaking changes, and design weaknesses are caught before an API ships. ## Core Features & Use Cases - API Linting: Validates OpenAPI/Swagger specs against REST conventions including kebab-case resources, camelCase fields, proper HTTP method usage, status codes, and error response formats. - Breaking Change Detection: Compares two spec versions to flag removed endpoints, changed field types, new required fields, and response shape modifications, with a CI gate that exits non-zero on breaking changes. - Design Scorecard: Grades API quality across consistency (30%), documentation (20%), security (20%), usability (15%), and performance (15%) with letter grades and recommendations. - Use Case: When reviewing a PR that adds endpoints, run the linter, breaking-change detector, and scorecard, then iterate until the linter is clean and the scorecard meets the agreed minimum grade. ## Quick Start Review the OpenAPI spec at openapi.json by running the linter, breaking-change detector against the previous version, and the scorecard, then report all findings and the grade.

Frequently Asked Questions about api-design-reviewer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I lint an OpenAPI specification for REST conventions?▼

Run api_linter.py with your OpenAPI JSON file to check naming conventions, HTTP method usage, URL structure, status codes, and error formats. It outputs a JSON report with issues grouped by severity and an overall quality score.

How to detect breaking changes between two API versions?▼

Run breaking_change_detector.py with the old and new OpenAPI specs to identify removed endpoints, changed field types, new required fields, and response shape changes. Use the --exit-on-breaking flag to fail CI pipelines when breaking changes are found.

What counts as a breaking change in a REST API?▼

Breaking changes include removing fields from responses, making optional fields required, changing field types, removing endpoints, and altering URL structures. Adding optional fields, new endpoints, or new response fields is considered safe and non-breaking.

Can API linting run in a CI/CD pipeline?▼

Yes, all three scripts support JSON output and exit codes suitable for CI integration. The linter reports violations, the breaking-change detector fails with --exit-on-breaking, and the scorecard fails below a --min-grade threshold.

What input formats does the API linter support?▼

The linter accepts standard OpenAPI/Swagger JSON specifications and also supports raw endpoint definition JSON with an endpoints object. OpenAPI specs receive full validation including info, servers, paths, components, and security sections.

Why does the scorecard give my API a low consistency grade?▼

Low consistency scores come from mixed naming conventions across paths, schemas, and properties, inconsistent response or error formats, and irregular status code usage. Standardize on kebab-case resources, camelCase fields, and PascalCase schemas to improve the grade.

Related Skills

Explore More Software Engineering Skills→
avdelag1avdelag1

openapi-spec-generation

Generate OpenAPI 3.1 specifications from code, annotations, or design-first inputs.

Community
Intermediate
alirezarezvanialirezarezvani
25.3k

api-design-reviewer

Lint OpenAPI specifications, detect breaking changes, and score REST API design quality.

Community
Advanced
yankeeinlondonyankeeinlondon
3

schematic-define

Define and validate REST and WebSocket API contracts for client generation.

Community
Advanced
MysMonMysMon
2

api-design

Design contract-first APIs with OpenAPI, GraphQL SDL, and Protobuf contracts.

Community
Advanced