Api Contract Review

This is the kind of review you want before API changes hit production. It catches the classics: POST used for idempotent operations, missing versioning in URL paths, JPA entities leaking into responses, and that cursed pattern of returning 200 with error messages in the body. The HTTP verb semantics table alone is worth having around. It's opinionated about URL path versioning over headers and pushes proper status codes hard, which is the right call. The examples are Java/Spring but the principles apply anywhere. Good for pre-release audits or when onboarding developers who haven't internalized REST conventions yet.

skills.sh installs: 315
GitHub stars: 771
last updated: Feb 8, 2026

View on GitHub

Install

$ npx -y skills add decebals/claude-code-java --skill api-contract-review --agent claude-code

Installs into .claude/skills of the current project.

Files

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	Retrieve resource	Yes	Yes	No
POST	Create new resource	No	No	Yes
PUT	Replace entire resource	Yes	No	Yes
PATCH	Partial update	No*	No	Yes
DELETE	Remove resource	Yes	No	Optional