rest-api-conventions
/rest-api-conventions
Generuje kontrolery REST, DTO, kontrakty odpowiedzi, stronicowanie, mapowanie kodów HTTP i wersjonowanie, zgodnie z konwencjami API.
- Autor
- rrezartprebreza ↗
- Repozytorium
- spring-boot-skills ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 22.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 7
- Skrypty
- 5
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 22.10.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 5 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: examples/bad-controller.java, examples/good-controller.java, templates/ApiResponse.java, templates/GlobalExceptionHandler.java, templates/PageResponse.java
Co robi i kiedy
Generuje kontrolery REST, DTO, kontrakty odpowiedzi, stronicowanie, mapowanie kodów HTTP i wersjonowanie, zgodnie z konwencjami API.
Oryginalny opis (EN)
Use when generating REST controllers, DTOs, success response contracts, pagination, HTTP status mapping, or API versioning. For RFC 9457 exception and error response formatting, use problem-details-rfc9457 unless the project explicitly requires a legacy error envelope.
Jak działa
- Project Contract
- ApiResponse Wrapper
- HTTP Status Mapping
- URL Conventions
- Pagination
- Legacy Envelope Exception Handler
- Gotchas
Podgląd SKILL.md
---
name: rest-api-conventions
description: >
Use when generating REST controllers, DTOs, success response contracts, pagination, HTTP status
mapping, or API versioning. For RFC 9457 exception and error response formatting, use
problem-details-rfc9457 unless the project explicitly requires a legacy error envelope.
---
# REST API Conventions
## Project Contract
Inspect existing controllers, tests and OpenAPI before choosing a response contract.
Preserve the project's IDs, response shape and versioning strategy. Do not migrate unrelated
endpoints while adding one route. The envelope below is an optional convention for a project
that uses it; plain success DTOs are equally valid. A 204 response has no body.
Success and error formats are independent: an existing success envelope can coexist with
RFC 9457 errors. Use one consistent error policy; choose the legacy error examples below only
when the project already requires that format.
Example success envelope:
```json
{
"success": true,
"data": { },
"error": null,
"timestamp": "2026-04-13T10:00:00Z"
}
```
Error response:
```json
{
"success": false,
"data": null,
"error": {
"code": "ORDER_NOT_FOUND",
"message": "Order with id 123 not found",
"details": []
},
"timestamp": "2026-04-13T10:00:00Z"
}
```
## ApiResponse Wrapper
```java
@JsonInclude(JsonInclude.Include.NON_NULL)
public record ApiResponse<T>(
boolean success,
T data,
ApiError error,
Instant timestamp
) {
public static <T> ApiResponse<T> ok(T data) {
return new ApiResponse<>(true, data, null, Instant.now());
}
public static <T> ApiResponse<T> error(String code, String message) {
return new ApiResponse<>(false, null, new ApiError(code, message, List.of()), Instant.now());
}
}
public record ApiError(String code, String message, List<String> details) {}
```
## HTTP Status Mapping
| Scenario | Status |
|----------|--------|
| GET — found | 200 |
| POST — created resource | 201 |
| PUT/PATCH — updated | 200 |
| DELETE — deleted | 204 (no body) |
| Validation failure | 400 |
| Unauthenticated | 401 |
| Forbidden | 403 |
| Not found | 404 |
| Conflict (duplicate) | 409 |
| Unhandled server error | 500 |
## URL Conventions
- **Plural nouns** for resources: `/orders`, `/users`, `/products`
- **Kebab-case** for multi-word: `/order-items`, not `/orderItems`
- **Versioning in path**: `/api/v1/orders`
- **Nested resources** max 2 levels: `/orders/{id}/items` ✅, `/orders/{id}/items/{itemId}/notes` ❌ — flatten to `/order-item-notes/{id}`
- **IDs**: preserve the existing ID type. UUIDs are an option, not an authorization mechanism.
```
GET /api/v1/orders → list (paginated)
POST /api/v1/orders → create
GET /api/v1/orders/{id} → get one
PUT /api/v1/orders/{id} → full update
PATCH /api/v1/orders/{id} → partial update
DELETE /api/v1/orders/{id} → delete
GET /api/v1/orders/{id}/items → nested resource
```
## Pagination
```json
{
"success": true,
"data": {
"content": [...],
"page": 0,
"size": 20,
"totalElements": 150,
"totalPages": 8,
"last": false
}
}
```
Query params: `?page=0&size=20&sort=createdAt,desc`
Use Spring Data `Pageable` in controllers:
```java
@GetMapping
public ApiResponse<PageResponse<OrderResponse>> list(Pageable pageable) {
return ApiResponse.ok(PageResponse.from(orderService.findAll(pageable).map(OrderResponse::from)));
}
```
**Cap the page size.** A bare `Pageable` accepts `?size=100000` from any client — one request can
drag your whole table into memory. Spring's default cap is 2000, still too high for most APIs:
```yaml
spring:
data:
web:
pageable:
default-page-size: 20
max-page-size: 100 # requests above this are silently clamped
```
The compiled [PageResponse](templates/PageResponse.java) fixes the JSON pagination contract.
Mapping entities to DTOs alone does not stabilize Spring Data `PageImpl` serialization.
Spring Data's `org.springframework.data.web.PagedModel` is another option when its shape fits
the API. Validate sort fields against an allowlist and add an ID tie-breaker to non-unique sorts.
## Legacy Envelope Exception Handler
```java
// Extends ResponseEntityExceptionHandler: without it the Exception.class catch-all turns
// malformed JSON, 405, bad path variables and unknown URLs into 500. Full version, verified
// against Boot 3 and 4: templates/GlobalExceptionHandler.java
@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
@ExceptionHandler(EntityNotFoundException.class)
public ResponseEntity<ApiResponse<Void>> handleNotFound(EntityNotFoundException ex) {
return ResponseEntity.status(404).body(ApiResponse.error("NOT_FOUND", ex.getMessage()));
}
@ExceptionHandler(AccessDeniedException.class) // @PreAuthorize denials surface here, not in the filter
public ResponseEntity<ApiResponse<Void>> handleAccessDenied(AccessDeniedException ex) {
return ResponseEntity.status(403).body(ApiResponse.error("FORBIDDEN", "Access denied"));
}
@Override // an @ExceptionHandler for this type would clash with the superclass at startup
protected ResponseEntity<Object> handleMethodArgumentNotValid(
MethodArgumentNotValidException ex, HttpHeaders headers, HttpStatusCode status, WebRequest request) {
List<String> details = ex.getBindingResult().getFieldErrors().stream()
.map(e -> e.getField() + ": " + e.getDefaultMessage()).toList();
return ResponseEntity.status(400).body(ApiResponse.validationError(details));
}
@Override // keep the framework's status + headers, return the envelope
protected ResponseEntity<Object> handleExceptionInternal(
Exception ex, Object body, HttpHeaders headers, HttpStatusCode status, WebRequest request) {
return ResponseEntity.status(status).headers(headers)
.body(ApiResponse.error("HTTP_" + status.value(), "Request could not be processed"));
}
@ExceptionHandler(Exception.class)
public ResponseEntity<ApiResponse<Void>> handleGeneric(Exception ex) {
return ResponseEntity.status(500).body(ApiResponse.error("INTERNAL_ERROR", "An unexpected error occurred"));
}
}
```
## Gotchas
- Agent writes an `Exception.class` catch-all in an advice that doesn't extend `ResponseEntityExceptionHandler` — malformed JSON, 405, type-mismatched path variables and unknown URLs all become 500
- Agent imposes a new envelope - preserve the existing success contract.
- Agent invents competing error handlers - use the project's established error contract.
- Agent puts exception handlers in controllers — always use `@RestControllerAdvice`
- Agent changes ID types while adding an endpoint - retain the existing ID scheme.
- Agent accepts unbounded `Pageable` — set `spring.data.web.pageable.max-page-size` or one request can pull the whole table
- Agent serializes PageImpl directly - map entities to DTOs, then wrap in PageResponse.
Pliki w paczce (7)
- SKILL.md 7 KB
- agents/openai.yaml 1 KB
- examples/bad-controller.java 1 KB
- examples/good-controller.java 1 KB
- templates/ApiResponse.java 1 KB
- templates/GlobalExceptionHandler.java 3 KB
- templates/PageResponse.java 1 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · rrezartprebreza/spring-boot-skills | 100 | MIT |
| rrezartprebreza/spring-boot-skills | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki 44e5b1a729cd (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100rest-api-design
Projektuje lub sprawdza kontrakty HTTP API: zasoby, operacje, statusy i błędy, stronicowanie, zgodność oraz wersjonowanie. - 100rest-controller-conventions
Pisze ręczne kontrolery REST w Symfony bez API Platform: atrybuty routingu, kody statusu, mapowanie payloadu i wersjonowanie. - 100common-api-design
Stosuje konwencje projektowania REST API: metody HTTP, kody statusu, wersjonowanie, stronicowanie i specyfikację OpenAPI. - 100api-design-rest
Stosuje reguły projektowania endpointów HTTP: kształty żądań i odpowiedzi, kody, formaty błędów, stronicowanie, wersje i limity. - 100api
Pomaga projektować, recenzować i zmieniać API HTTP, REST lub GraphQL: endpointy, nazwy zasobów, odpowiedzi błędów, paginacja, wersjonowanie, idempotencja i kontrakty między usługami. - 100api-design
Podaje konwencje REST API: struktura URL, metody HTTP, kody statusu, paginacja, filtrowanie, odpowiedzi błędów i wersjonowanie, przy projektowaniu, przeglądzie i standaryzacji tras.