api-contract-review

# 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 | *PATCH can be idempotent depending on implementation ### Common Mistakes ```java // ❌ POST for retrieval @PostMapping("/users/search") public List<User> searchUsers(@RequestBody SearchCriteria criteria) { } // ✅ GET with query params (or POST only if criteria is very complex) @GetMapping("/users") public List<User> searchUs...