Какие значения можно вернуть в запросе

Значения, которые можно вернуть в HTTP запросе

В REST API Java приложение возвращает HTTP ответ, который состоит из статус-кода, заголовков и тела ответа.

1. HTTP Статус-коды (Status Codes)

Статус-код указывает на результат обработки запроса:

2xx — Успех

• 200 OK — запрос успешно обработан
• 201 Created — ресурс успешно создан (обычно для POST)
• 202 Accepted — запрос принят, но обработка еще идёт
• 204 No Content — успешно, но нет тела ответа (обычно для DELETE)

@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    return ResponseEntity.ok(user);  // 200 OK
}

@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
    User saved = userService.save(user);
    return ResponseEntity.status(HttpStatus.CREATED).body(saved);  // 201 Created
}

@DeleteMapping("/users/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    userService.delete(id);
    return ResponseEntity.noContent().build();  // 204 No Content
}

4xx — Ошибка клиента

• 400 Bad Request — неверный формат запроса (например, invalid JSON)
• 401 Unauthorized — требуется аутентификация
• 403 Forbidden — доступ запрещён (нет прав)
• 404 Not Found — ресурс не найден
• 409 Conflict — конфликт (например, дублирование)
• 422 Unprocessable Entity — данные не валидны

@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    return userService.findById(id)
        .map(ResponseEntity::ok)
        .orElseGet(() -> ResponseEntity.notFound().build());  // 404
}

@PostMapping("/users")
public ResponseEntity<ErrorResponse> createUser(@RequestBody User user) {
    if (userService.emailExists(user.getEmail())) {
        return ResponseEntity.status(HttpStatus.CONFLICT)
            .body(new ErrorResponse("Email already exists"));
    }
    // ...
}

5xx — Ошибка сервера

• 500 Internal Server Error — необработанная ошибка
• 503 Service Unavailable — сервис недоступен

2. Тело ответа (Response Body)

JSON объект — самый частый формат в REST API

public class UserResponse {
    private Long id;
    private String name;
    private String email;
    // getters, setters
}

@GetMapping("/users/{id}")
public ResponseEntity<UserResponse> getUser(@PathVariable Long id) {
    User user = userService.findById(id);
    return ResponseEntity.ok(new UserResponse(user.getId(), user.getName(), user.getEmail()));
}

Возвращаемый JSON:

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com"
}

JSON массив — для коллекций

@GetMapping("/users")
public ResponseEntity<List<UserResponse>> getAllUsers() {
    List<UserResponse> users = userService.findAll()
        .stream()
        .map(u -> new UserResponse(u.getId(), u.getName(), u.getEmail()))
        .collect(Collectors.toList());
    return ResponseEntity.ok(users);
}

Возвращаемый JSON:

[
  {"id": 1, "name": "John", "email": "john@example.com"},
  {"id": 2, "name": "Jane", "email": "jane@example.com"}
]

Пустой ответ — для DELETE операций

@DeleteMapping("/users/{id}")
public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
    userService.delete(id);
    return ResponseEntity.noContent().build();  // 204 No Content, пустое тело
}

3. Стандартная структура Error Response

public class ErrorResponse {
    private String error;
    private String message;
    private LocalDateTime timestamp;
    private int status;
    private String path;
    private Map<String, String> validationErrors;  // для ошибок валидации

    // constructors, getters
}

@ExceptionHandler(ValidationException.class)
public ResponseEntity<ErrorResponse> handleValidationError(
        ValidationException ex, 
        HttpServletRequest request) {
    ErrorResponse error = new ErrorResponse(
        "Validation Failed",
        ex.getMessage(),
        LocalDateTime.now(),
        HttpStatus.BAD_REQUEST.value(),
        request.getRequestURI(),
        ex.getErrors()
    );
    return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(error);
}

Возвращаемый JSON ошибки:

{
  "error": "Validation Failed",
  "message": "User validation failed",
  "timestamp": "2024-03-22T10:30:00Z",
  "status": 400,
  "path": "/api/users",
  "validationErrors": {
    "email": "Invalid email format",
    "name": "Name is required"
  }
}

4. Заголовки ответа (Response Headers)

@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    return ResponseEntity.ok()
        .header("X-Custom-Header", "value")
        .header("Cache-Control", "max-age=3600")
        .body(user);
}

Частые заголовки:

• Content-Type: application/json — формат тела ответа
• Content-Length — размер тела
• Cache-Control — кеширование
• Location — URL созданного ресурса (для 201)
• X-Page, X-Total-Count — для pagination

5. Wrapping ответов (успех + данные)

public class ApiResponse<T> {
    private boolean success;
    private T data;
    private String message;
    private List<String> errors;
}

@GetMapping("/users/{id}")
public ResponseEntity<ApiResponse<User>> getUser(@PathVariable Long id) {
    return userService.findById(id)
        .map(user -> ResponseEntity.ok(new ApiResponse<>(true, user, null, null)))
        .orElseGet(() -> ResponseEntity.notFound().build());
}

Лучшие практики

1. Всегда указывай подходящий HTTP статус-код
2. Возвращай структурированный ответ (даже для ошибок)
3. Используй DTOs (Data Transfer Objects) вместо сырых entity
4. Валидируй данные и возвращай понятные ошибки
5. Документируй endpoints (Swagger/OpenAPI) с примерами ответов
6. Используй ResponseEntity для большего контроля над ответом