Чем input list отличается от patch list

Input list и patch list — не универсальные термины с одним значением для всех языков и API. Но в задачах, где нужно передать или изменить набор элементов, различие обычно такое: input list описывает данные, которые поступают на обработку, а patch list — изменения, которые надо применить к уже существующему набору.

Проще говоря, первый отвечает на вопрос «какой список передать?», второй — «что именно в текущем списке поменять?». Из-за этой разницы одинаковый на вид массив может приводить к совершенно разным результатам.

Input list: передать набор целиком

В простом сценарии input list — это входной список значений. Например, клиент отправляет роли пользователя: ["reader", "editor"]. Приложение может создать объект с такими ролями, обработать их или заменить ими прежний набор. Само выражение input list не говорит, какой именно вариант выбран: это определяется задачей и контрактом конкретного метода.

Если API трактует этот список как полное новое состояние, передача ["reader", "editor"] означает: после запроса у пользователя должны остаться именно эти две роли. Если раньше была роль admin, она исчезнет. Но другой API может воспринять массив лишь как значения для добавления. Поэтому слово «input» само по себе не обещает ни замену, ни добавление — оно лишь указывает, что список служит входными данными.

Patch list: описать изменения

Patch list обычно содержит не конечный набор, а операции над существующими данными. Допустим, у пользователя сейчас есть роли ["reader", "admin"], и требуется убрать admin, добавив editor. Вместо отправки всего итогового списка можно передать инструкции: удалить одно значение и добавить другое. Сервер применит их к текущему состоянию.

Один из известных форматов для такого подхода — JSON Patch. В нём операции записываются как объекты с названиями действий, например add, remove или replace, и указанием пути к изменяемому значению. В таком формате patch list — это последовательность команд, а не список ролей пользователя. Порядок команд может иметь значение: удаление элемента массива иногда меняет индексы следующих элементов.

Слово «patch» встречается и в других форматах. Запрос с HTTP-методом PATCH, например, может передавать частичное представление объекта, а не список явных операций. Одни API считают такой фрагмент инструкцией обновить только указанные поля, другие задают дополнительные правила для массивов. Поэтому название метода или поля не заменяет документацию формата.

Почему их нельзя подменять друг другом

Главное различие — в отношении к состоянию, которое уже хранится на сервере. Input list может задавать набор для обработки или, если так договорились разработчики, новое состояние целиком. Patch list предполагает, что есть исходный список, к которому будут применены изменения. Если отправить patch туда, где сервер ожидает полную замену, он может не понять инструкции. Если отправить полный список туда, где ожидаются операции, сервер может воспринять элементы не так, как задумано.

Представим текущий набор меток: ["urgent", "billing"]. Полный список ["urgent", "support"] может означать замену: метка billing пропадёт. Patch с операцией добавления support может, напротив, сохранить обе старые метки и получить ["urgent", "billing", "support"]. Чтобы удалить billing, в patch нужно отдельно указать такое действие — если формат его поддерживает.

У patch есть и особенности применения. Операция «добавить» не всегда ведёт себя так же, как присваивание списка; повторное выполнение команды может дать другой результат. Некоторые обновления идемпотентны: их повтор не меняет итог после первого применения. Другие — нет, например повторное добавление элемента в список, где разрешены дубликаты. Полагаться на это без проверки контракта рискованно.

Что уточнить в документации

Перед отправкой списка полезно выяснить несколько вещей: он заменяет прежний набор или дополняет его; как удаляются элементы; важны ли порядок и повторы; что означает пустой список; допустимы ли отсутствующие поля и значения null. Для patch дополнительно нужно понять, какие операции доступны и как выбираются элементы массива — по индексу, идентификатору или другому ключу.

Особенно внимательно стоит относиться к пустому списку. В одном API [] может означать «удалить все элементы», в другом — «ничего не менять», а в третьем быть недопустимым значением. Это не тонкость терминологии, а разница, которая способна привести к потере данных или к обновлению не того набора.

Практическое правило простое: если передаётся итоговый набор, перед вами input list в смысле входных данных; если передаются команды или правила частичного изменения существующего набора — это patch list. Но окончательный ответ всегда задаёт конкретный API: проверять нужно не одно название, а формат запроса и описанное поведение массива.