rest-api-conventions

Name: rest-api-conventions
Author: rrezartprebreza

174stars33forks

How to install rest-api-conventions?

rrezartprebreza/spring-boot-skills/rest-api-conventions

$npx -y skills add rrezartprebreza/spring-boot-skills --skill rest-api-conventions

Installs into the current project.

Summary

Use when generating REST controllers, response wrappers, DTOs, error handlers, or any HTTP-facing code. Defines response envelope, HTTP status mapping, pagination, and versioning.

Files · 1

View on GitHub

SKILL.md

1	# REST API Conventions
2
3	## Response Envelope
4
5	All endpoints return a consistent envelope:
6
7	```json
8	{
9	"success": true,
10	"data": { },
11	"error": null,
12	"timestamp": "2026-04-13T10:00:00Z"
13	}
14	```
15
16	Error response:
17	```json
18	{
19	"success": false,
20	"data": null,
21	"error": {
22	"code": "ORDER_NOT_FOUND",
23	"message": "Order with id 123 not found",
24	"details": []
25	},
26	"timestamp": "2026-04-13T10:00:00Z"
27	}
28	```
29
30	## ApiResponse Wrapper
31
32	```java
33	@JsonInclude(JsonInclude.Include.NON_NULL)
34	public record ApiResponse<T>(
35	boolean success,
36	T data,
37	ApiError error,
38	Instant timestamp
39	) {
40	public static <T> ApiResponse<T> ok(T data) {
41	return new ApiResponse<>(true, data, null, Instant.now());
42	}
43
44	public static <T> ApiResponse<T> error(String code, String message) {
45	return new ApiResponse<>(false, null, new ApiError(code, message, List.of()), Instant.now());
46	}
47	}
48
49	public record ApiError(String code, String message, List<String> details) {}
50	```
51
52	## HTTP Status Mapping
53
54	\| Scenario \| Status \|
55	\|----------\|--------\|
56	\| GET — found \| 200 \|
57	\| POST — created resource \| 201 \|
58	\| PUT/PATCH — updated \| 200 \|
59	\| DELETE — deleted \| 204 (no body) \|
60	\| Validation failure \| 400 \|
61	\| Unauthenticated \| 401 \|
62	\| Forbidden \| 403 \|
63	\| Not found \| 404 \|
64	\| Conflict (duplicate) \| 409 \|
65	\| Unhandled server error \| 500 \|
66
67	## URL Conventions
68
69	- Plural nouns for resources: `/orders`, `/users`, `/products`
70	- Kebab-case for multi-word: `/order-items`, not `/orderItems`
71	- Versioning in path: `/api/v1/orders`
72	- Nested resources max 2 levels: `/orders/{id}/items` ✅, `/orders/{id}/items/{itemId}/notes` ❌ — flatten to `/order-item-notes/{id}`
73	- IDs as UUIDs in path, never auto-increment integers exposed in URL
74
75	```
76	GET /api/v1/orders → list (paginated)
77	POST /api/v1/orders → create
78	GET /api/v1/orders/{id} → get one
79	PUT /api/v1/orders/{id} → full update
80	PATCH /api/v1/orders/{id} → partial update
81	DELETE /api/v1/orders/{id} → delete
82	GET /api/v1/orders/{id}/items → nested resource
83	```
84
85	## Pagination
86
87	```json
88	{
89	"success": true,
90	"data": {
91	"content": [...],
92	"page": 0,
93	"size": 20,
94	"totalElements": 150,
95	"totalPages": 8,
96	"last": false
97	}
98	}
99	```
100
101	Query params: `?page=0&size=20&sort=createdAt,desc`
102
103	Use Spring Data `Pageable` in controllers:
104	```java
105	@GetMapping
106	public ApiResponse<Page<OrderResponse>> list(Pageable pageable) {
107	return ApiResponse.ok(orderService.findAll(pageable).map(OrderResponse::from));
108	}
109	```
110
111	Cap the page size. A bare `Pageable` accepts `?size=100000` from any client — one request can
112	drag your whole table into memory. Spring's default cap is 2000, still too high for most APIs:
113
114	```yaml
115	spring:
116	data:
117	web:
118	pageable:
119	default-page-size: 20
120	max-page-size: 100 # requests above this are silently clamped
121	```
122
123	## Global Exception Handler
124
125	```java
126	@RestControllerAdvice
127	@RequiredArgsConstructor
128	public class GlobalExceptionHandler {
129
130	@ExceptionHandler(EntityNotFoundException.class)
131	public ResponseEntity<ApiResponse<Void>> handleNotFound(EntityNotFoundException ex) {
132	return ResponseEntity.status(404).body(ApiResponse.error("NOT_FOUND", ex.getMessage()));
133	}
134
135	@ExceptionHandler(MethodArgumentNotValidException.class)
136	public ResponseEntity<ApiResponse<Void>> handleValidation(MethodArgumentNotValidException ex) {
137	List<String> details = ex.getBindingResult().getFieldErrors().stream()
138	.map(e -> e.getField() + ": " + e.getDefaultMessage()).toList();
139	return ResponseEntity.status(400)
140	.body(new ApiResponse<>(false, null, new ApiError("VALIDATION_FAILED", "Invalid input", details), Instant.now()));
141	}
142
143	@ExceptionHandler(Exception.class)
144	public ResponseEntity<ApiResponse<Void>> handleGeneric(Exception ex) {
145	return ResponseEntity.status(500).body(ApiResponse.error("INTERNAL_ERROR", "An unexpected error occurred"));
146	}
147	}
148	```
149
150	## Gotchas
151	- Agent returns raw objects without envelope — always wrap in `ApiResponse.ok(...)`
152	- Agent uses `ResponseEntity<Map<String, Object>>` for errors — use `ApiResponse`
153	- Agent puts exception handlers in controllers — always use `@RestControllerAdvice`
154	- Agent uses `Long` IDs in URLs — use `UUID`
155	- Agent accepts unbounded `Pageable` — set `spring.data.web.pageable.max-page-size` or one request can pull the whole table
156	- Agent returns `Page<Entity>` serialized directly — exposes Hibernate internals; map to DTOs first

People who liked this also viewed

6 picks

Type

rest-api-conventions

174stars33forks

View on GitHub

How to install rest-api-conventions?

rrezartprebreza/spring-boot-skills/rest-api-conventions

$npx -y skills add rrezartprebreza/spring-boot-skills --skill rest-api-conventions

Installs into the current project.

Summary

Use when generating REST controllers, response wrappers, DTOs, error handlers, or any HTTP-facing code. Defines response envelope, HTTP status mapping, pagination, and versioning.

Files · 1

View on GitHub

SKILL.md

1	# REST API Conventions
2
3	## Response Envelope
4
5	All endpoints return a consistent envelope:
6
7	```json
8	{
9	"success": true,
10	"data": { },
11	"error": null,
12	"timestamp": "2026-04-13T10:00:00Z"
13	}
14	```
15
16	Error response:
17	```json
18	{
19	"success": false,
20	"data": null,
21	"error": {
22	"code": "ORDER_NOT_FOUND",
23	"message": "Order with id 123 not found",
24	"details": []
25	},
26	"timestamp": "2026-04-13T10:00:00Z"
27	}
28	```
29
30	## ApiResponse Wrapper
31
32	```java
33	@JsonInclude(JsonInclude.Include.NON_NULL)
34	public record ApiResponse<T>(
35	boolean success,
36	T data,
37	ApiError error,
38	Instant timestamp
39	) {
40	public static <T> ApiResponse<T> ok(T data) {
41	return new ApiResponse<>(true, data, null, Instant.now());
42	}
43
44	public static <T> ApiResponse<T> error(String code, String message) {
45	return new ApiResponse<>(false, null, new ApiError(code, message, List.of()), Instant.now());
46	}
47	}
48
49	public record ApiError(String code, String message, List<String> details) {}
50	```
51
52	## HTTP Status Mapping
53
54	\| Scenario \| Status \|
55	\|----------\|--------\|
56	\| GET — found \| 200 \|
57	\| POST — created resource \| 201 \|
58	\| PUT/PATCH — updated \| 200 \|
59	\| DELETE — deleted \| 204 (no body) \|
60	\| Validation failure \| 400 \|
61	\| Unauthenticated \| 401 \|
62	\| Forbidden \| 403 \|
63	\| Not found \| 404 \|
64	\| Conflict (duplicate) \| 409 \|
65	\| Unhandled server error \| 500 \|
66
67	## URL Conventions
68
69	- Plural nouns for resources: `/orders`, `/users`, `/products`
70	- Kebab-case for multi-word: `/order-items`, not `/orderItems`
71	- Versioning in path: `/api/v1/orders`
72	- Nested resources max 2 levels: `/orders/{id}/items` ✅, `/orders/{id}/items/{itemId}/notes` ❌ — flatten to `/order-item-notes/{id}`
73	- IDs as UUIDs in path, never auto-increment integers exposed in URL
74
75	```
76	GET /api/v1/orders → list (paginated)
77	POST /api/v1/orders → create
78	GET /api/v1/orders/{id} → get one
79	PUT /api/v1/orders/{id} → full update
80	PATCH /api/v1/orders/{id} → partial update
81	DELETE /api/v1/orders/{id} → delete
82	GET /api/v1/orders/{id}/items → nested resource
83	```
84
85	## Pagination
86
87	```json
88	{
89	"success": true,
90	"data": {
91	"content": [...],
92	"page": 0,
93	"size": 20,
94	"totalElements": 150,
95	"totalPages": 8,
96	"last": false
97	}
98	}
99	```
100
101	Query params: `?page=0&size=20&sort=createdAt,desc`
102
103	Use Spring Data `Pageable` in controllers:
104	```java
105	@GetMapping
106	public ApiResponse<Page<OrderResponse>> list(Pageable pageable) {
107	return ApiResponse.ok(orderService.findAll(pageable).map(OrderResponse::from));
108	}
109	```
110
111	Cap the page size. A bare `Pageable` accepts `?size=100000` from any client — one request can
112	drag your whole table into memory. Spring's default cap is 2000, still too high for most APIs:
113
114	```yaml
115	spring:
116	data:
117	web:
118	pageable:
119	default-page-size: 20
120	max-page-size: 100 # requests above this are silently clamped
121	```
122
123	## Global Exception Handler
124
125	```java
126	@RestControllerAdvice
127	@RequiredArgsConstructor
128	public class GlobalExceptionHandler {
129
130	@ExceptionHandler(EntityNotFoundException.class)
131	public ResponseEntity<ApiResponse<Void>> handleNotFound(EntityNotFoundException ex) {
132	return ResponseEntity.status(404).body(ApiResponse.error("NOT_FOUND", ex.getMessage()));
133	}
134
135	@ExceptionHandler(MethodArgumentNotValidException.class)
136	public ResponseEntity<ApiResponse<Void>> handleValidation(MethodArgumentNotValidException ex) {
137	List<String> details = ex.getBindingResult().getFieldErrors().stream()
138	.map(e -> e.getField() + ": " + e.getDefaultMessage()).toList();
139	return ResponseEntity.status(400)
140	.body(new ApiResponse<>(false, null, new ApiError("VALIDATION_FAILED", "Invalid input", details), Instant.now()));
141	}
142
143	@ExceptionHandler(Exception.class)
144	public ResponseEntity<ApiResponse<Void>> handleGeneric(Exception ex) {
145	return ResponseEntity.status(500).body(ApiResponse.error("INTERNAL_ERROR", "An unexpected error occurred"));
146	}
147	}
148	```
149
150	## Gotchas
151	- Agent returns raw objects without envelope — always wrap in `ApiResponse.ok(...)`
152	- Agent uses `ResponseEntity<Map<String, Object>>` for errors — use `ApiResponse`
153	- Agent puts exception handlers in controllers — always use `@RestControllerAdvice`
154	- Agent uses `Long` IDs in URLs — use `UUID`
155	- Agent accepts unbounded `Pageable` — set `spring.data.web.pageable.max-page-size` or one request can pull the whole table
156	- Agent returns `Page<Entity>` serialized directly — exposes Hibernate internals; map to DTOs first

People who liked this also viewed

6 picks

Type