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

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

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

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

Ответ 1

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

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

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

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

Ответ 2

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

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

Запрет на использование полей только для чтения в PUT является плохой идеей, потому что это потребует от клиентов отменить поля, которые они получили от вас в GET. Это требует, чтобы клиент более тесно связан с вашими данными и семантикой, чем они действительно должны быть. Клиенты будут рассматривать это головную боль, ненужное осложнение и прямое из вас, чтобы добавить к их бремени. Принимая данные, полученные от вашего ПОЛУЧЕНИЯ, изменяя одну интересующую область и отправляя ее обратно с помощью PUT, вы должны быть простым и удобным для клиента клиентом. Не усложняйте ситуацию, когда вам это не нужно.