Можно ли целиком заменить ресурс с помощью PATCH?

Можно ли целиком заменить ресурс с помощью PATCH?

Краткий ответ: да, это возможно, но не является стандартной практикой и противоречит семантике HTTP-методов, если делать это регулярно. PATCH предназначен для частичных изменений, а для полной замены ресурса существует метод PUT.

Чтобы дать развернутый ответ, нужно рассмотреть различия между PATCH, PUT и POST, а также понять, как спецификация HTTP трактует эти методы.

Семантика HTTP-методов: PUT vs PATCH

Согласно стандарту RFC 7231 (и более раннему RFC 2616), методы имеют четкое назначение:

• PUT — используется для полной замены ресурса. Клиент передает новое представление ресурса, и сервер заменяет существующее представление целиком на переданное. Если ресурс не существовал, PUT может его создать. PUT идемпотентен: многократный вызов с одними и теми же данными дает тот же результат, что и один вызов.
• PATCH — введен в RFC 5789 специально для частичного обновления. Клиент отправляет набор инструкций (патч-документ), описывающих, как изменить существующий ресурс. Результат PATCH не обязательно идемпотентен, хотя это желательно.

Техническая возможность полной замены через PATCH

Формально ничто не мешает отправить через PATCH такой набор изменений, который эквивалентен полной замене. Например, если использовать формат JSON Patch (RFC 6902), можно отправить операцию replace для всего документа.

Пример JSON Patch для полной замены:

[
  { "op": "replace", "path": "", "value": {"id": 123, "title": "Новый заголовок", "content": "Полностью новое содержание"} }
]

Или даже более явно с add, если ресурс рассматривается как новый:

[
  { "op": "add", "path": "", "value": {/* весь новый объект */} }
]

Таким образом, технически сервер может интерпретировать такой PATCH-запрос как команду на полную замену и выполнить ее. Однако здесь кроется несколько важных проблем.

Почему это плохая практика?

1. Нарушение принципа наименьшего удивления (Principle of Least Astonishment):

    Разработчик или система, читающая ваш API-контракт (например, из документации OpenAPI/Swagger), ожидает, что `PATCH` выполняет частичное обновление. Использование его для полной замены вводит в заблуждение, усложняет понимание и поддержку API.

1. Потеря семантической ясности и идемпотентности:

    `PUT` гарантированно идемпотентен. `PATCH`, используемый для замены, может таковым не быть, если логика на сервере сложная (например, зависит от текущего состояния). Это создает риски при повторе запросов в ненадежных сетях.

1. Проблемы с валидацией и безопасностью:

    Эндпоинты для `PATCH` часто имеют более мягкие правила валидации (например, все поля опциональны), так как ожидают частичных данных. При полной замене могут быть пропущены обязательные для создания/замены поля, что приведет к ошибкам или corrupt-данным.

1. Несовместимость с клиентскими библиотеками и кэшированием:

    Промежуточное ПО (кеши, прокси) и клиентские библиотеки могут по-разному обрабатывать `PATCH` и `PUT`. Нестандартное использование метода может привести к некорректному кэшированию или неожиданному поведению инструментов.

Правильный подход: разделение ответственности

Для создания четкого, предсказуемого и удобного в использовании API следует придерживаться RESTful-практик:

• Используйте PUT /api/resource/{id} для полной замены ресурса. Тело запроса должно содержать полное новое представление.
• Используйте PATCH /api/resource/{id} только для частичных обновлений. Четко документируйте поддерживаемый формат патча (JSON Patch, JSON Merge Patch, собственный формат).
• Используйте POST /api/resource для создания ресурса, когда ID определяется сервером.

Пример на Node.js (Express):

// ПЛОХО: PATCH используется для полной замены (запутывает)
app.patch('/api/articles/:id', (req, res) => {
    // Опасная логика: просто перезаписываем весь документ данными из тела
    const updatedArticle = req.body;
    ArticleModel.replaceOne({_id: req.params.id}, updatedArticle);
    res.sendStatus(200);
});

// ХОРОШО: Разделение по семантике
app.put('/api/articles/:id', (req, res) => {
    // PUT - для полной замены. Ожидаем ВСЕ обязательные поля.
    const fullUpdate = req.body;
    if (!fullUpdate.title || !fullUpdate.content) {
        return res.status(400).json({error: 'Для PUT требуются все поля'});
    }
    ArticleModel.replaceOne({_id: req.params.id}, fullUpdate);
    res.json(fullUpdate);
});

app.patch('/api/articles/:id', (req, res) => {
    // PATCH - для частичного обновления. Обрабатываем JSON Patch.
    const patchOperations = req.body; // Например, массив операций JSON Patch
    try {
        const currentArticle = ArticleModel.findById(req.params.id);
        const patchedArticle = applyJsonPatch(currentArticle, patchOperations); // Специальная функция применения патча
        ArticleModel.updateOne({_id: req.params.id}, patchedArticle);
        res.json(patchedArticle);
    } catch (err) {
        res.status(400).json({error: 'Неверный формат PATCH'});
    }
});

Вывод

Можно ли? Технически — да, сервер может обработать PATCH-запрос как команду на полную замену. Нужно ли? Абсолютно нет. Это считается антипаттерном в дизайне REST API.

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