Метод HTTP PATCH. Содержимое в теле запроса

Я разрабатываю REST API, используя Symfony2. У меня есть система бронирования, и я хотел бы отправить клиенту электронное письмо, когда его бронирование будет подтверждено администратором.

У меня есть ресурс резервирования, и мы можем подтвердить бронирование, используя этот URL-адрес:

ПАТЧ localhost/:id/validate

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

Если нет, то каким должен быть правильный путь?

Спасибо, Мехди.


http rest http-patch
person Mehdi Chamouma    schedule 24.03.2014    source источник
comment
На днях я использовал swagger для документации API и впервые столкнулся с запросом PATCH, раньше я не знал об этом типе запроса. Затем я поискал его и нашел это pic.dhe.ibm.com/infocenter/tivihelp/v58r1/, если кто-то может объяснить лучше, буду очень признателен. Спасибо   -  person Syed Raza Mehdi    schedule 22.09.2014

Ответы (2)


arrow_upward
10
arrow_downward

Во-первых, о ресурсах и REST.

Когда вы говорите PATCH localhost/:id/validate, вы должны читать это как «Я обновляю существующую проверку». «Подтвердить» — это ничто, даже правильный английский. Проверка — это не ресурс, это действие. Когда у вас есть действия (глаголы) в вашем URL, ваш API — это RPC, а не REST. Также см. мой более подробный ответ здесь.

Итак, подумайте, что вы на самом деле делаете. Один из ниже:

  • Вы обновляете бронирование
  • Вы создаете подтверждение бронирования
  • Вы заменяете бронирование проверенной версией этого бронирования.

Первый вариант имеет смысл и является самым простым.
PATCH /reservations/{id} status=valid
Удерживает ли уже резервирование адрес электронной почты? Тогда используйте это. В противном случае рассмотрите возможность отправки электронного письма.
PATCH /reservations/{id} status=valid&[email protected].
Это читается как «обновите электронное письмо и статус бронирования, указав следующие значения». Поскольку PATCH (и POST) могут иметь побочные эффекты, отправка почты вполне допустима.

Второй необходим, когда одно бронирование имеет много подтверждений. Или когда REST-клиентам необходимо отслеживать проверки отдельно от резервирований (например, GET /reservations/{id}/validations/{id}). В таких случаях имеет смысл иметь ресурс Validation.
POST /reservations/{id}/validations.
Если в бронировании нет адреса электронной почты, отправьте его вместе с ним.
POST /reservations/{id}/validations [email protected].
Это читается как «проведите проверку для этого бронирование по электронной почте [email protected]». Это читается как «Я делаю новую проверку этого бронирования». Поскольку POST (и PATCH) могут иметь побочные эффекты, отправка почты вполне допустима.

Третий случай важен из-за побочных эффектов. Если вы хотите представить способ, с помощью которого клиенты могут быть уверены в отсутствии побочных эффектов, это пригодится.
PUT /reservations/{id} room=12&date=1970-01-01&status=valid&[email protected]
Это читается как "заменить существующее резервирование проверкой со статусом подтверждено". Поскольку PUT никогда не должен иметь побочных эффектов, клиент может быть уверен, что повторное воспроизведение этого (например, при сетевых ошибках, большой нагрузке или что-то еще) никогда не приведет к тому, что пользователь будет спамить.

person berkes    schedule 15.06.2017
comment
Идеальный ответ. Спасибо - person Mehdi Chamouma; 29.06.2017
comment
Я предполагаю, что предложение после PUT должно читаться следующим образом: «Это читается как замена существующего резервирования резервированием, которое имеет подтвержденный статус. ' или: 'Это читается как замена существующего бронирования другим, имеющим подтвержденный статус. ' - person user1708042; 12.02.2021

arrow_upward
1
arrow_downward

Если цель состоит в проверке, не будет ли POST более подходящим? Понятие проверки больше похоже на RPC, чем на ресурс. Согласно RFC 5789, PATCH следует использовать для частичного изменения ресурса.

person NathanAldenSr    schedule 24.03.2014
comment
При проверке ресурс переходит из состояния невалидации в состояние проверки. Вот почему я подумал, что ресурс частично изменен. При этом я не создавал никаких новых ресурсов, так зачем использовать метод post? - person Mehdi Chamouma; 24.03.2014
comment
POST обычно используется с веб-службами в стиле RPC. Возможно, вы изменяете ресурс, но URL-адрес выглядит как RPC. Это единственная причина, по которой я предложил POST. Возможно, вам следует использовать PATCH в самом URL-адресе ресурса и просто опустить /validate. Затем используйте сообщение в теле контента, чтобы выяснить, как исправить ресурс. - person NathanAldenSr; 24.03.2014
comment
@MehdiChamouma Вот почему я подумал, что ресурс частично изменен, это правильное рассуждение. Вы правы, что POST здесь неуместен, а PATCH более уместен. - person berkes; 15.06.2017