Доменом приложения HTTP является передача документов по сети. Ваш «REST API» - это фасад, который действует как хранилище документов и выполняет полезную работу в качестве побочного эффекта передачи документов. См. Джим Уэббер (2011) .
Итак, основные идиомы c в том, что мы публикуем документ или отправляем кучу правок в существующий документ, и сервер интерпретирует их изменяется и делает что-то полезное.
Таким образом, простой протокол, основанный на существующей семантике удаленной авторизации, может выглядеть как
GET /orders?user=user_id
Make local edits to the representation of that list provided by the server
PUT /orders?user=user_id
Семантика того, как это сделать, должна быть понимается обоими концами обмена. Может быть, вы удалите ненужные элементы из списка? Возможно, для каждой записи в списке есть запись о статусе, и вы меняете статус с активного на просроченный.
В Интернете вместо семантики удаленной авторизации мы склонны вместо этого использовать отправку форм. Вы откуда-то получаете пустую форму, заполняете ее самостоятельно, отправляете ее в указанный почтовый ящик, и лицо, ответственное за обработку этого почтового ящика, выполняет свою работу.
Итак, мы загружаем пустую форму в наш браузер, и мы вносим в него изменения, а затем публикуем его на ресурсе, указанном в форме.
GET /the-blank-form?user=user_id
Make changes in the form...
POST ????
Каким должен быть target-uri? Веб-браузер не волнует; он просто собирается отправить форму любой цели, указанной в представлении, которое он получил. Одним из ответов может быть отправка его обратно туда, где мы его получили:
POST /the-blank-form?user=user_id
И это прекрасно работает (если вы правильно управляете метаданными). Другая возможность - вместо этого отправить изменения в ресурс, который вы ожидаете, чтобы отразить эти изменения:
POST /orders?user=user_id
, и получается , что тоже работает нормально. HTTP имеет интересную семантику аннулирования кэша , встроенную в спецификацию, поэтому мы можем удостовериться, что устаревшая копия клиента или ресурс сбора заказов признан недействительным, используя этот же ресурс в качестве цели вызова POST.
В настоящее время мой API удовлетворяет таблице в нижней части REST, поэтому любая дополнительная конечная точка нарушит его. Будет ли это фатальным или нет, вот в чем вопрос.
Нет, все будет хорошо - просто добавьте / расширите обработчик POST на соответствующем ресурсе для обработки новой семантики.
Более длинный ответ: таблица в Википедии - хорошее представление о распространенных практиках; но обычные практики не совсем на высоте. Частично проблема заключается в том, что REST включает единый интерфейс . Помимо прочего, это означает, что все ресурсы понимают одну и ту же семантику сообщений. Понятие «ресурсы коллекции» и «ресурсы члена» не существует в REST - семантика для них одинакова.
Другой способ сказать, что компонент общего назначения никогда не знает, является ли ресурс, с которым он разговаривает, является коллекцией или членом. Все небезопасные методы (POST / PUT / PATCH / DELETE / et c) подразумевают аннулирование представлений target-uri.
Теперь POST, как это происходит, означает «делать что-то, что не было стандартизировано "- см. Fielding 2009 . Этот метод имеет наименьшее количество ограничений semanti c.
Метод POST запрашивает, чтобы целевой ресурс обработал представление, заключенное в запросе, в соответствии с собственной спецификацией семантики c ресурса. - RF C 7231
Для обработчика POST прекрасно подходит ветвление на основе содержимого полезной нагрузки запроса; если вы видите X, создайте что-то, если вы видите Y, удалите что-то еще. Это аналогично наличию двух разных веб-форм с различной семантикой, которые подчиняются одному и тому же целевому ресурсу.