api-contract-review

Name: api-contract-review
Author: decebals

686stars133forks

How to install api-contract-review?

decebals/claude-code-java/api-contract-review

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

Installs into the current project.

Summary

Review REST API contracts for HTTP semantics, versioning, backward compatibility, and response consistency. Use when user asks "review API", "check endpoints", "REST review", or before releasing API changes.

Files · 1

View on GitHub

SKILL.md

1	# API Contract Review Skill
2
3	Audit REST API design for correctness, consistency, and compatibility.
4
5	## When to Use
6	- User asks "review this API" / "check REST endpoints"
7	- Before releasing API changes
8	- Reviewing PR with controller changes
9	- Checking backward compatibility
10
11	---
12
13	## Quick Reference: Common Issues
14
15	\| Issue \| Symptom \| Impact \|
16	\|-------\|---------\|--------\|
17	\| Wrong HTTP verb \| POST for idempotent operation \| Confusion, caching issues \|
18	\| Missing versioning \| `/users` instead of `/v1/users` \| Breaking changes affect all clients \|
19	\| Entity leak \| JPA entity in response \| Exposes internals, N+1 risk \|
20	\| 200 with error \| `{"status": 200, "error": "..."}` \| Breaks error handling \|
21	\| Inconsistent naming \| `/getUsers` vs `/users` \| Hard to learn API \|
22
23	---
24
25	## HTTP Verb Semantics
26
27	### Verb Selection Guide
28
29	\| Verb \| Use For \| Idempotent \| Safe \| Request Body \|
30	\|------\|---------\|------------\|------\|--------------\|
31	\| GET \| Retrieve resource \| Yes \| Yes \| No \|
32	\| POST \| Create new resource \| No \| No \| Yes \|
33	\| PUT \| Replace entire resource \| Yes \| No \| Yes \|
34	\| PATCH \| Partial update \| No* \| No \| Yes \|
35	\| DELETE \| Remove resource \| Yes \| No \| Optional \|
36
37	*PATCH can be idempotent depending on implementation
38
39	### Common Mistakes
40
41	```java
42	// ❌ POST for retrieval
43	@PostMapping("/users/search")
44	public List<User> searchUsers(@RequestBody SearchCriteria criteria) { }
45
46	// ✅ GET with query params (or POST only if criteria is very complex)
47	@GetMapping("/users")
48	public List<User> searchUsers(
49	@RequestParam String name,
50	@RequestParam(required = false) String email) { }
51
52	// ❌ GET for state change
53	@GetMapping("/users/{id}/activate")
54	public void activateUser(@PathVariable Long id) { }
55
56	// ✅ POST or PATCH for state change
57	@PostMapping("/users/{id}/activate")
58	public ResponseEntity<Void> activateUser(@PathVariable Long id) { }
59
60	// ❌ POST for idempotent update
61	@PostMapping("/users/{id}")
62	public User updateUser(@PathVariable Long id, @RequestBody UserDto dto) { }
63
64	// ✅ PUT for full replacement, PATCH for partial
65	@PutMapping("/users/{id}")
66	public User replaceUser(@PathVariable Long id, @RequestBody UserDto dto) { }
67
68	@PatchMapping("/users/{id}")
69	public User updateUser(@PathVariable Long id, @RequestBody UserPatchDto dto) { }
70	```
71
72	---
73
74	## API Versioning
75
76	### Strategies
77
78	\| Strategy \| Example \| Pros \| Cons \|
79	\|----------\|---------\|------\|------\|
80	\| URL path \| `/v1/users` \| Clear, easy routing \| URL changes \|
81	\| Header \| `Accept: application/vnd.api.v1+json` \| Clean URLs \| Hidden, harder to test \|
82	\| Query param \| `/users?version=1` \| Easy to add \| Easy to forget \|
83
84	### Recommended: URL Path
85
86	```java
87	// ✅ Versioned endpoints
88	@RestController
89	@RequestMapping("/api/v1/users")
90	public class UserControllerV1 { }
91
92	@RestController
93	@RequestMapping("/api/v2/users")
94	public class UserControllerV2 { }
95
96	// ❌ No versioning
97	@RestController
98	@RequestMapping("/api/users") // Breaking changes affect everyone
99	public class UserController { }
100	```
101
102	### Version Checklist
103	- [ ] All public APIs have version in path
104	- [ ] Internal APIs documented as internal (or versioned too)
105	- [ ] Deprecation strategy defined for old versions
106
107	---
108
109	## Request/Response Design
110
111	### DTO vs Entity
112
113	```java
114	// ❌ Entity in response (leaks internals)
115	@GetMapping("/{id}")
116	public User getUser(@PathVariable Long id) {
117	return userRepository.findById(id).orElseThrow();
118	// Exposes: password hash, internal IDs, lazy collections
119	}
120
121	// ✅ DTO response
122	@GetMapping("/{id}")
123	public UserResponse getUser(@PathVariable Long id) {
124	User user = userService.findById(id);
125	return UserResponse.from(user); // Only public fields
126	}
127	```
128
129	### Response Consistency
130
131	```java
132	// ❌ Inconsistent responses
133	@GetMapping("/users")
134	public List<User> getUsers() { } // Returns array
135
136	@GetMapping("/users/{id}")
137	public User getUser(@PathVariable Long id) { } // Returns object
138
139	@GetMapping("/users/count")
140	public int countUsers() { } // Returns primitive
141
142	// ✅ Consistent wrapper (optional but recommended for large APIs)
143	@GetMapping("/users")
144	public ApiResponse<List<UserResponse>> getUsers() {
145	return ApiResponse.success(userService.findAll());
146	}
147
148	// Or at minimum, consistent structure:
149	// - Collections: always wrapped or always raw (pick one)
150	// - Single items: always object
151	// - Counts/stats: always object { "count": 42 }
152	```
153
154	### Pagination
155
156	```java
157	// ❌ No pagination on collections
158	@GetMapping("/users")
159	public List<User> getAllUsers() {
160	return userRepository.findAll(); // Could be millions
161	}
162
163	// ✅ Paginated
164	@GetMapping("/users")
165	public Page<UserResponse> getUsers(
166	@RequestParam(defaultValue = "0") int page,
167	@RequestParam(defaultValue = "20") int size) {
168	return userService.findAll(PageRequest.of(page, size));
169	}
170	```
171
172	---
173
174	## HTTP S

People who liked this also viewed

6 picks

Type

api-contract-review

686stars133forks

View on GitHub

How to install api-contract-review?

decebals/claude-code-java/api-contract-review

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# API Contract Review Skill
2
3	Audit REST API design for correctness, consistency, and compatibility.
4
5	## When to Use
6	- User asks "review this API" / "check REST endpoints"
7	- Before releasing API changes
8	- Reviewing PR with controller changes
9	- Checking backward compatibility
10
11	---
12
13	## Quick Reference: Common Issues
14
15	\| Issue \| Symptom \| Impact \|
16	\|-------\|---------\|--------\|
17	\| Wrong HTTP verb \| POST for idempotent operation \| Confusion, caching issues \|
18	\| Missing versioning \| `/users` instead of `/v1/users` \| Breaking changes affect all clients \|
19	\| Entity leak \| JPA entity in response \| Exposes internals, N+1 risk \|
20	\| 200 with error \| `{"status": 200, "error": "..."}` \| Breaks error handling \|
21	\| Inconsistent naming \| `/getUsers` vs `/users` \| Hard to learn API \|
22
23	---
24
25	## HTTP Verb Semantics
26
27	### Verb Selection Guide
28
29	\| Verb \| Use For \| Idempotent \| Safe \| Request Body \|
30	\|------\|---------\|------------\|------\|--------------\|
31	\| GET \| Retrieve resource \| Yes \| Yes \| No \|
32	\| POST \| Create new resource \| No \| No \| Yes \|
33	\| PUT \| Replace entire resource \| Yes \| No \| Yes \|
34	\| PATCH \| Partial update \| No* \| No \| Yes \|
35	\| DELETE \| Remove resource \| Yes \| No \| Optional \|
36
37	*PATCH can be idempotent depending on implementation
38
39	### Common Mistakes
40
41	```java
42	// ❌ POST for retrieval
43	@PostMapping("/users/search")
44	public List<User> searchUsers(@RequestBody SearchCriteria criteria) { }
45
46	// ✅ GET with query params (or POST only if criteria is very complex)
47	@GetMapping("/users")
48	public List<User> searchUsers(
49	@RequestParam String name,
50	@RequestParam(required = false) String email) { }
51
52	// ❌ GET for state change
53	@GetMapping("/users/{id}/activate")
54	public void activateUser(@PathVariable Long id) { }
55
56	// ✅ POST or PATCH for state change
57	@PostMapping("/users/{id}/activate")
58	public ResponseEntity<Void> activateUser(@PathVariable Long id) { }
59
60	// ❌ POST for idempotent update
61	@PostMapping("/users/{id}")
62	public User updateUser(@PathVariable Long id, @RequestBody UserDto dto) { }
63
64	// ✅ PUT for full replacement, PATCH for partial
65	@PutMapping("/users/{id}")
66	public User replaceUser(@PathVariable Long id, @RequestBody UserDto dto) { }
67
68	@PatchMapping("/users/{id}")
69	public User updateUser(@PathVariable Long id, @RequestBody UserPatchDto dto) { }
70	```
71
72	---
73
74	## API Versioning
75
76	### Strategies
77
78	\| Strategy \| Example \| Pros \| Cons \|
79	\|----------\|---------\|------\|------\|
80	\| URL path \| `/v1/users` \| Clear, easy routing \| URL changes \|
81	\| Header \| `Accept: application/vnd.api.v1+json` \| Clean URLs \| Hidden, harder to test \|
82	\| Query param \| `/users?version=1` \| Easy to add \| Easy to forget \|
83
84	### Recommended: URL Path
85
86	```java
87	// ✅ Versioned endpoints
88	@RestController
89	@RequestMapping("/api/v1/users")
90	public class UserControllerV1 { }
91
92	@RestController
93	@RequestMapping("/api/v2/users")
94	public class UserControllerV2 { }
95
96	// ❌ No versioning
97	@RestController
98	@RequestMapping("/api/users") // Breaking changes affect everyone
99	public class UserController { }
100	```
101
102	### Version Checklist
103	- [ ] All public APIs have version in path
104	- [ ] Internal APIs documented as internal (or versioned too)
105	- [ ] Deprecation strategy defined for old versions
106
107	---
108
109	## Request/Response Design
110
111	### DTO vs Entity
112
113	```java
114	// ❌ Entity in response (leaks internals)
115	@GetMapping("/{id}")
116	public User getUser(@PathVariable Long id) {
117	return userRepository.findById(id).orElseThrow();
118	// Exposes: password hash, internal IDs, lazy collections
119	}
120
121	// ✅ DTO response
122	@GetMapping("/{id}")
123	public UserResponse getUser(@PathVariable Long id) {
124	User user = userService.findById(id);
125	return UserResponse.from(user); // Only public fields
126	}
127	```
128
129	### Response Consistency
130
131	```java
132	// ❌ Inconsistent responses
133	@GetMapping("/users")
134	public List<User> getUsers() { } // Returns array
135
136	@GetMapping("/users/{id}")
137	public User getUser(@PathVariable Long id) { } // Returns object
138
139	@GetMapping("/users/count")
140	public int countUsers() { } // Returns primitive
141
142	// ✅ Consistent wrapper (optional but recommended for large APIs)
143	@GetMapping("/users")
144	public ApiResponse<List<UserResponse>> getUsers() {
145	return ApiResponse.success(userService.findAll());
146	}
147
148	// Or at minimum, consistent structure:
149	// - Collections: always wrapped or always raw (pick one)
150	// - Single items: always object
151	// - Counts/stats: always object { "count": 42 }
152	```
153
154	### Pagination
155
156	```java
157	// ❌ No pagination on collections
158	@GetMapping("/users")
159	public List<User> getAllUsers() {
160	return userRepository.findAll(); // Could be millions
161	}
162
163	// ✅ Paginated
164	@GetMapping("/users")
165	public Page<UserResponse> getUsers(
166	@RequestParam(defaultValue = "0") int page,
167	@RequestParam(defaultValue = "20") int size) {
168	return userService.findAll(PageRequest.of(page, size));
169	}
170	```
171
172	---
173
174	## HTTP S

People who liked this also viewed

6 picks

Type