Что такое идемпотентные методы HTTP?

Что такое идемпотентные методы HTTP?

Идемпотентность в контексте HTTP — это свойство метода запроса, означающее, что многократное выполнение одного и того же запроса с одинаковыми данными должно приводить к одному и тому же результату, как если бы он был выполнен только один раз. Иными словами, повторные идемпотентные запросы не должны вызывать дополнительных изменений на сервере после первого успешного выполнения.

Ключевые идемпотентные методы HTTP

Согласно спецификации RFC 7231, идемпотентными методами являются:

• GET: Запрашивает представление ресурса. Повторные GET-запросы должны возвращать одинаковые данные (если ресурс не был изменён другими операциями).
• HEAD: Аналогичен GET, но возвращает только заголовки без тела ответа. Также идемпотентен.
• OPTIONS: Возвращает информацию о доступных методах для ресурса. Идемпотентен.
• TRACE: Используется для диагностики, возвращая полученный запрос. Идемпотентен.
• PUT: Используется для полного обновления ресурса по указанному URI. Повторная отправка одного и того же PUT-запроса должна оставлять ресурс в том же состоянии (A=5).
• DELETE: Удаляет указанный ресурс. После первого успешного удаления ресурса его больше нет, поэтому повторные запросы DELETE обычно возвращают тот же статус (например, 404 Not Found или 410 Gone), что и делает метод идемпотентным. Важно: успешный ответ на первый DELETE — это часто 200 OK или 204 No Content, а на последующие — 404.

НЕидемпотентный метод

• POST: Используется для создания ресурса или выполнения неидемпотентных действий. Каждый повторный POST-запрос может привести к созданию нового ресурса или другому побочному эффекту (например, списанию денег со счёта). Поэтому POST не является идемпотентным.

Практическое значение идемпотентности

Идемпотентность критически важна для:

1. Надёжности сетевых взаимодействий: В случае сбоев (таймаут, разрыв соединения) клиент может безопасно повторять идемпотентные запросы без риска дублирования операций.
2. Механизмов повтора (Retry): Автоматические повторные отправки запросов при временных ошибках (например, 500 Internal Server Error) безопасны для идемпотентных методов.
3. Кэширования: Идемпотентность GET и HEAD позволяет кэшировать их ответы.

Примеры на PHP

Рассмотрим реализацию идемпотентного и неидемпотентного эндпоинта.

Пример 1: Идемпотентный метод PUT для обновления пользователя

// Обработчик PUT /api/users/123
if ($_SERVER['REQUEST_METHOD'] === 'PUT') {
    $userId = (int) $_GET['id'];
    $inputData = json_decode(file_get_contents('php://input'), true);

    // Предположим, что $inputData содержит ['name' => 'Иван', 'email' => 'ivan@example.com']
    // Идемпотентность: сколько бы раз мы ни отправили этот запрос, пользователь с ID 123
    // всегда будет иметь эти значения.
    $sql = "UPDATE users SET name = :name, email = :email WHERE id = :id";
    $stmt = $pdo->prepare($sql);
    $stmt->execute([
        ':name' => $inputData['name'],
        ':email' => $inputData['email'],
        ':id' => $userId
    ]);

    // Ответ
    http_response_code(200);
    echo json_encode(['message' => 'User updated']);
}

Пример 2: НЕидемпотентный метод POST для создания заказа

// Обработчик POST /api/orders
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $inputData = json_decode(file_get_contents('php://input'), true);

    // НЕидемпотентность: каждый повторный запрос создаст новый заказ в базе!
    $sql = "INSERT INTO orders (user_id, product_id, amount) VALUES (:user_id, :product_id, :amount)";
    $stmt = $pdo->prepare($sql);
    $stmt->execute([
        ':user_id' => $inputData['user_id'],
        ':product_id' => $inputData['product_id'],
        ':amount' => $inputData['amount']
    ]);

    $newOrderId = $pdo->lastInsertId();

    // Дополнительный НЕидемпотентный побочный эффект: списание денег с баланса
    $updateBalanceSql = "UPDATE users SET balance = balance - :amount WHERE id = :user_id";
    $stmt = $pdo->prepare($updateBalanceSql);
    $stmt->execute([
        ':amount' => $inputData['amount'],
        ':user_id' => $inputData['user_id']
    ]);

    http_response_code(201);
    echo json_encode(['order_id' => $newOrderId]);
}

Важные нюансы

• Идемпотентность определяется на уровне бизнес-логики, а не протокола. Сервер обязан её обеспечивать для соответствующих методов. Например, некорректная реализация PUT, которая увеличивает счётчик (например, views = views + 1), нарушает идемпотентность.
• Статус ответа при повторных вызовах может различаться (например, первый DELETE возвращает 200, а второй — 404), но итоговое состояние сервера (отсутствие ресурса) должно быть идентичным.
• Для обеспечения идемпотентности в неидемпотентных по своей природе операциях (например, приём платежа) используются специальные техники: идемпотентные ключи (idempotency keys). Клиент генерирует уникальный ключ для операции и отправляет его в заголовке (например, Idempotency-Key: <uuid>). Сервер, сохраняя результат первой обработки, при повторном запросе с тем же ключом возвращает сохранённый ответ, не выполняя операцию снова.

Таким образом, понимание и правильное применение идемпотентности — это основа построения надёжных, отказоустойчивых и предсказуемых RESTful API.