Блог

Я пытаюсь создать api, который соответствует спецификации json: api.

В моем api есть три ресурса /task , /item и /result . Задача имеет поля name , description и state . Элемент имеет поля itemName . A count сохраняется на сервере для элемента, а count возвращается, когда пользователь получает элемент с GET запросом. Увеличивается count на стороне сервера при обновлении элемента. Между задачей и элементом существует отношение «один ко многим». В некотором смысле элемент добавляется к задаче. При изменении состояния задач скрипт запускается на стороне сервера для выполнения некоторой обработки связанных элементов. После завершения работы скрипта выходные данные доступны в результирующем ресурсе.

Согласно спецификации, я использую POST глагол для создания задачи и PATCH для обновления задачи. Мне просто нужна одна конечная точка, которая обрабатывает как создание, так и обновление (добавление) элемента. Но я не уверен, какой глагол использовать? Могу ли я использовать PATCH для обновления элемента, но также и для создания элемента, если он не существует?

Я также подумал, что, возможно, мне следует использовать PUT глагол. Но, насколько я понимаю, этот глагол используется для простой замены ресурса, а не для его обновления. Я не думаю, что это подходит для моего пользовательского варианта, поскольку количество элементов увеличивается при обновлении, поэтому замена его — это не то, что я хочу сделать. Но счетчик обрабатывается на стороне сервера, поэтому у пользователя все равно нет возможности «заменить» счетчик.

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

Это общее понимание — неправильное, но распространенное.

Реестр IANA документирует авторитетную ссылку на семантику методов http. Большинство распространенных из них определены в RFC 7231; ИСПРАВЛЕНИЕ определяется в RFC 5789.

PUT является подходящим выбором, когда тело сообщения является полным представлением того, каким вы хотите видеть ресурс. Может быть, проще подумать о «сохранении файла»; PUT описывает, как клиент ожидает, что документ будет выглядеть после его сохранения.

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

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