rest-api-conventions

# REST API Conventions ## Response Envelope All endpoints return a consistent 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` - *...