api-contract-reviewlisted
Install: claude install-skill decebals/claude-code-java
# 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