Дизайн RESTful API: должны ли быть неизменяемыми данные в обновлении (PUT)?

Question

Я нахожусь в процессе реализации RESTful API, и я не уверен насчет поведения, принятого сообществом, для наличия данных, которые не могут измениться. Например, в моем API есть ресурс «файл», который при создании содержит ряд полей, которые нельзя изменить после создания, таких как двоичные данные файла и некоторые метаданные, связанные с ним. Кроме того, «файл» может иметь письменное описание и связанные теги.

Мой вопрос касается обновления одного из этих файловых ресурсов. GET определенного «файла» вернет все метаданные, описание и теги, связанные с файлом, а также двоичные данные файла. Должен ли PUT определенного ресурса 'file' включать поля 'только для чтения'? Я понимаю, что это может быть закодировано любым способом: а) включить поля только для чтения в данные PUT и затем убедиться, что они соответствуют оригиналу (или выдать ошибку), или б) игнорировать присутствие полей только для чтения в данных PUT потому что они не могут измениться, никогда не выдавая ошибку, если они не совпадают или отсутствуют, потому что логика их игнорирует.

Похоже, что это может пойти в любую сторону и быть приемлемым. Второй способ игнорирования полей только для чтения может быть более компактным, поскольку клиент API может пропустить отправку этих данных только для чтения, если они захотят; что хорошо для людей, которые знают, что делают ...

Answer 1

Если только данные, доступные только для чтения, составляют значительную часть данных (до такой степени, что передача данных только для чтения оказывает заметное влияние на сетевой трафик и время отклика), вы должны написать сервис, чтобы принимать только чтение поля в PUT и проверьте их на наличие изменений. Проще вводить и выводить одни и те же данные.

Посмотрите на это так: вы можете сделать включение полей только для чтения необязательным в PUT, но вам все равно придется / нужно написать код в службе, чтобы убедиться, что все полученные поля только для чтения содержат ожидаемые ценности. Вы должны написать проверку только для чтения в любом случае.

Запретить поля «только для чтения» в PUT - плохая идея, поскольку от клиентов потребуется убирать поля, полученные от вас в GET. Это требует, чтобы клиент был более тесно связан с вашими данными и семантикой, чем они действительно должны быть. Клиенты сочтут это головной болью, ненужным осложнением и совершенно неприемлемым для вас бременем. Взятие данных, полученных из вашего GET, изменение одной области интересов и отправка их вам обратно с помощью PUT должно быть для клиента просто умопомрачительным круговым обходом. Не усложняйте вещи, когда вам не нужно.

Answer 2

Лично оба способа приемлемы ... однако на вашем месте я выберу вариант А (проверьте поля только для чтения, чтобы убедиться, что они не изменены, иначе выведите ошибку). В зависимости от масштаба вашего проекта, вы не можете предположить, что потребители знают о вашем Restful WS, потому что большинство из них не читает документацию или WADL, даже если они опытные. :)

Если вы не предоставите потребителю немедленную обратную связь о том, что определенные поля доступны только для чтения, у них будет ложное предположение, что ваш веб-сервис позаботится обо всех внесенных изменениях без двойной проверки, ИЛИ как только они обнаруживают «несогласованные» обновления, они жалуются другим, что ваш веб-сервис содержит ошибки.

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

1. Не обрабатывать запрос. Отправьте код конфликта 409 и конкретное сообщение об ошибке.
2. Обработка запроса, отправка 200 OK и сообщение о том, что изменения, внесенные в поля только для чтения, игнорируются.