Я нахожусь в процессе написания RESTful API. По большей части все работает отлично, но есть несколько случаев, когда я не имею дело с ресурсом, когда вещи начинают ломаться. Хотя существует миллион способов решения проблемы, с которой я сталкиваюсь, я ищу отзывы о том, какой из них был бы наиболее идеальным.
Для простоты скажем, что API — это timer
,
timer
вовремя.start
а также stop
,start
таймер они POST
некоторые данные, связанные с timer
который создает новый timer
до тех пор, пока у них еще нет timer
Бег.stop
на timer
обновляет timer
отметить это как неактивное.В настоящее время у меня есть эта настройка следующим образом:
Таймер запуска:
POST /api/v1/timer
Body: [
'thing1' => 'something',
'thing2' => 'somethingelse
]
Response: 204
Таймер остановки:
PUT /api/v1/timer/stop
Body:
Response: 204
Так как пользователь может иметь только 1 timer
активным, казалось, не имеет смысла возвращать timer
id
как и в более традиционном вызове CRUD.
Я прочитал несколько постов, которые предлагают использовать POST
метод на stop
вызов, чтобы вызвать остановку вместо PUT
, Я полагаю, это тоже имеет смысл … это действительно ломается, когда вы не имеете дело с традиционным ресурсом.
Конечно, я мог бы также переписать его, чтобы вернуть timer
ресурс, но для меня это добавляет накладные расходы на клиента, который должен затем отслеживать timer
id
когда они хотят остановить (или удалить) активный таймер.
Любой вклад здесь будет принята с благодарностью.
Подумайте, как бы вы реализовали это требование на веб-сайте.
Вы будете смотреть на какую-то веб-страницу, специфичную для текущего пользователя. Там будет ссылка с надписью начало. Вы получите эту ссылку и откроете форму, которая даст вам возможность переопределить параметры по умолчанию, связанные с запуском таймера.
Когда вы отправляете форму, браузер создает запрос на основе правил обработки формы HTML. Поскольку это не безопасная операция, метод, вероятно, будет отправкой, а данные формы будут application / x-www-form-urlencoded в теле сообщения.
Поскольку изменение состояния таймера, вероятно, приведет к изменению представления исходной страницы, вероятно, там, где форма попросит вас отправить POST. Успешный ответ на запрос POST скажет браузеру сделать недействительным кэшированное представление исходной страницы.
Когда вы перезагрузите эту страницу, ссылка «старт» исчезнет, и вместо нее будет ссылка «стоп». Работа с этой ссылкой будет практически такой же -> нажатие на ссылку приведет вас к форме, отправит форму обратно на исходную страницу и лишит законной силы предыдущее представление. Когда вы перезагружаете страницу, таймер выключается, и стартовая ссылка снова становится доступной.
GET /DarthVaderYellowMerrigold
GET /DarthVaderYellowMerrigold/start
POST /DarthVaderYellowMerrigold
GET /DarthVaderYellowMerrigold
GET /DarthVaderYellowMerrigold/stop
POST /DarthVaderYellowMerrigold
GET /DarthVaderYellowMerrigold
Есть несколько вещей, которые вы можете сделать, чтобы очистить это (возвращая новое представление в ответ на успешное POST, например, с соответствующими заголовками Content-Location, так что клиенту не нужно извлекать данные), но Основная идея — это звук.
Сделайте это машиночитаемым способом, и вы получите REST API.
Это в основном означает документирование того, как машина должна понимать, для чего предназначена каждая ссылка. Msgstr «Чтобы перейти к форме таймера запуска, найдите эту ссылку; чтобы перейти к форме таймера остановки, найдите эту ссылку».
Вы, вероятно, оставите HTTP и URI в покое, но разумно заменить HTML, например, одним из типов гипермедиа JSON. Или поместить ссылки в заголовки HTML, а не в представление.
Конечно, у HTML есть непосредственное преимущество: вы можете просто пройтись по API «вручную» и убедиться, что все работает, используя ваш любимый браузер на рабочем столе. Компромиссы имеются в большом количестве.
Других решений пока нет …