api-contract-review
Audit your REST API design against best practices for HTTP verb selection, versioning strategies, and status code correctness. Catches common mistakes like wrong HTTP methods, missing API versions, entity leaks, and improper error handling that break client compatibility.
API Contract Review audits REST endpoints for HTTP semantics, versioning, and backward compatibility issues.
AI-generated summary based on this skill's SKILL.md
Install
decebals/claude-code-java/api-contract-review · repository language: Shell
git clone https://github.com/decebals/claude-code-java
cp -r claude-code-java/.claude/skills/api-contract-review ~/.claude/skills/api-contract-reviewnpx skillfed install decebals/claude-code-java/api-contract-reviewFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
What does api-contract-review check in my REST API endpoints?
api-contract-review audits your REST API design against best practices for HTTP verb selection, versioning strategies, and status code correctness. It catches common mistakes like wrong HTTP methods, missing API versions, entity leaks, and improper error handling that break client compatibility.
How can I review my REST API endpoints for HTTP semantics?
api-contract-review reviews REST API contracts for HTTP semantics and correctness, validating that your endpoints use appropriate HTTP verbs, status codes, and response patterns. It checks controller HTTP verb usage and ensures your API follows REST conventions.
Can api-contract-review audit my API versioning strategy?
Yes. api-contract-review audits API versioning and backward compatibility, including versioning in URL paths and deprecation strategy. It identifies breaking changes before releasing API updates and validates your approach to maintaining client compatibility across versions.
What response design issues does api-contract-review validate?
api-contract-review validates response design, DTOs, and error handling patterns. It checks for entity leaks in REST responses, validates DTO vs entity usage, reviews API status codes and error handling, and audits REST API security in error responses to prevent anti-patterns like 200 OK errors.
Does api-contract-review check endpoint naming conventions?
Yes. api-contract-review checks endpoint naming, URL structure, and design consistency. It validates REST endpoint naming conventions and ensures your API follows consistent design patterns across all routes.
How does api-contract-review help identify breaking changes?
api-contract-review reviews your API for breaking changes before releasing updates. By auditing versioning strategy, backward compatibility, deprecation practices, and response consistency, it helps you catch compatibility issues that would break existing clients.
SKILL.md
rendered from the published skill — quoted content, verbatim
API Contract Review Skill
Audit REST API design for correctness, consistency, and compatibility.
When to Use
- User asks "review this API" / "check REST endpoints"
- Before releasing API changes
- Reviewing PR with controller changes
- Checking backward compatibility
Quick Reference: Common Issues
| Issue | Symptom | Impact |
|---|---|---|
| Wrong HTTP verb | POST for idempotent operation | Confusion, caching issues |
| Missing versioning | /users instead of /v1/users |
Breaking changes affect all clients |
| Entity leak | JPA entity in response | Exposes internals, N+1 risk |
| 200 with error | {"status": 200, "error": "..."} |
Breaks error handling |
| Inconsistent naming | /getUsers vs /users |
Hard to learn API |
HTTP Verb Semantics
Verb Selection Guide
| Verb | Use For | Idempotent | Safe | Request Body |
|---|---|---|---|---|
| GET |
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 2 files
.claude/skills/api-contract-review/README.md
.claude/skills/api-contract-review/SKILL.md