Для чего используется каждый http метод?

HTTP методы и их применение

В REST API используется несколько HTTP методов, каждый с четкой семантикой. Расскажу про каждый и как я их применяю:

1. GET - Получение данных

Используется для безопасного чтения данных БЕЗ изменения состояния сервера.

@GetMapping("/users")
public ResponseEntity<List<UserDTO>> getAllUsers(
    @RequestParam(required = false) String role,
    @RequestParam(defaultValue = "0") int page) {
    return ResponseEntity.ok(userService.getUsers(role, page));
}

@GetMapping("/users/{id}")
public ResponseEntity<UserDTO> getUserById(@PathVariable Long id) {
    return ResponseEntity.ok(userService.getUserById(id));
}

Характеристики:

• Не должен изменять данные
• Безопасен (можно вызывать многократно)
• Кешируется браузером
• Параметры передаются в URL

2. POST - Создание новых ресурсов

Используется для создания нового ресурса на сервере.

@PostMapping("/users")
public ResponseEntity<UserDTO> createUser(@RequestBody CreateUserRequest request) {
    UserDTO createdUser = userService.createUser(request);
    return ResponseEntity
        .status(HttpStatus.CREATED)
        .location(URI.create("/users/" + createdUser.getId()))
        .body(createdUser);
}

@PostMapping("/orders/{id}/confirm")
public ResponseEntity<OrderDTO> confirmOrder(@PathVariable Long id) {
    OrderDTO confirmedOrder = orderService.confirm(id);
    return ResponseEntity.ok(confirmedOrder);
}

Характеристики:

• Не идемпотентен (вызов дважды создаст два ресурса)
• Данные в теле запроса
• Должен вернуть 201 Created с Location заголовком
• Может иметь побочные эффекты

3. PUT - Полное обновление ресурса

Используется для полной замены ресурса (все поля).

@PutMapping("/users/{id}")
public ResponseEntity<UserDTO> updateUserFully(
    @PathVariable Long id,
    @RequestBody UpdateUserRequest request) {
    UserDTO updatedUser = userService.replaceUser(id, request);
    return ResponseEntity.ok(updatedUser);
}

Важно: PUT требует полного объекта. Если отправить неполные данные, остальные поля могут быть очищены.

// Пример: этот запрос может очистить некоторые поля
{
    "name": "John"
    // email, phone и другие поля не указаны
}

Характеристики:

• Идемпотентен (вызов дважды даст тот же результат)
• Полная замена ресурса
• Должен содержать все необходимые поля
• Вернет 200 OK или 204 No Content

4. PATCH - Частичное обновление

Используется для частичного обновления ресурса (только некоторые поля).

@PatchMapping("/users/{id}")
public ResponseEntity<UserDTO> updateUserPartially(
    @PathVariable Long id,
    @RequestBody Map<String, Object> updates) {
    UserDTO updatedUser = userService.updatePartially(id, updates);
    return ResponseEntity.ok(updatedUser);
}

// Или с использованием JSON Patch
@PatchMapping("/users/{id}")
public ResponseEntity<UserDTO> patchUser(
    @PathVariable Long id,
    @RequestBody JsonPatch patch) {
    UserDTO updatedUser = userService.applyPatch(id, patch);
    return ResponseEntity.ok(updatedUser);
}

Характеристики:

• Обновляет только указанные поля
• Может быть не идемпотентен в зависимости от операции
• Передает только измененные данные
• Вернет 200 OK

5. DELETE - Удаление ресурса

Используется для удаления ресурса.

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

@DeleteMapping("/posts/{id}/comments/{commentId}")
public ResponseEntity<Void> deleteComment(
    @PathVariable Long id,
    @PathVariable Long commentId) {
    commentService.deleteComment(commentId);
    return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
}

Характеристики:

• Идемпотентен (удаление несуществующего ресурса вернет 404)
• Вернет 204 No Content или 200 OK
• Может быть асинхронным (202 Accepted для длительного удаления)

6. HEAD - Как GET, но без тела

Аналогичен GET, но не возвращает тело ответа. Используется для проверки наличия ресурса.

@HeadMapping("/users/{id}")
public ResponseEntity<Void> checkUserExists(@PathVariable Long id) {
    if (!userService.exists(id)) {
        return ResponseEntity.notFound().build();
    }
    return ResponseEntity.ok().build();
}

7. OPTIONS - Описание доступных методов

Опишет какие методы доступны для ресурса. Часто генерируется автоматически Spring.

OPTIONS /users
Allow: GET, POST, HEAD, OPTIONS

Сравнительная таблица

Практический пример REST API

@RestController
@RequestMapping("/api/v1/products")
public class ProductController {
    
    @GetMapping
    public ResponseEntity<Page<ProductDTO>> listProducts(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "10") int size) {
        return ResponseEntity.ok(
            productService.getProducts(PageRequest.of(page, size))
        );
    }
    
    @GetMapping("/{id}")
    public ResponseEntity<ProductDTO> getProduct(@PathVariable Long id) {
        return ResponseEntity.ok(productService.getById(id));
    }
    
    @PostMapping
    public ResponseEntity<ProductDTO> createProduct(
        @RequestBody @Valid CreateProductRequest request) {
        ProductDTO product = productService.create(request);
        return ResponseEntity
            .status(HttpStatus.CREATED)
            .location(URI.create("/api/v1/products/" + product.getId()))
            .body(product);
    }
    
    @PutMapping("/{id}")
    public ResponseEntity<ProductDTO> updateProduct(
        @PathVariable Long id,
        @RequestBody @Valid UpdateProductRequest request) {
        return ResponseEntity.ok(productService.update(id, request));
    }
    
    @PatchMapping("/{id}")
    public ResponseEntity<ProductDTO> partialUpdate(
        @PathVariable Long id,
        @RequestBody Map<String, Object> updates) {
        return ResponseEntity.ok(productService.updatePartially(id, updates));
    }
    
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteProduct(@PathVariable Long id) {
        productService.delete(id);
        return ResponseEntity.noContent().build();
    }
}

Когда что использовать

• GET: Любое чтение данных
• POST: Создание нового ресурса, сложные фильтры, действия (не CRUD)
• PUT: Полное обновление известного ресурса
• PATCH: Частичное обновление, когда важна экономия трафика
• DELETE: Удаление ресурса

Важно следовать REST принципам для консистентного и предсказуемого API.