Как определить страницу редактирования в REST API?

Question

В Play приложение я проектирования, вот некоторые из моих маршрутов

POST /visits      controllers.Visit.create 
GET  /visits      controllers.Visit.visits 
GET  /visits/:id     controllers.Visit.visit(id: Long) 
PUT  /visits/:id     controllers.Visit.update(id: Long) 
DELETE /visits/:id     controllers.Visit.delete(id: Long) 

Я поддерживающих интерфейс браузера тоже. Я следую инструкциям, которые я здесь видел: RESTful on Play! framework

Я могу легко предоставить HTML-шаблон для отображения подробной информации об одном конкретном посещении или списке посещений. Но как «правая страница» легко впадает в это, что должно быть предварительно заполнено информацией из определенного посещения? Я могу легко сделать что-то вроде: GET /visits/:id/edit controllers.Visit.edit(id: Long), которое вернет предварительно заполненную страницу с информацией о посещении, или я могу создать статическую HTML-страницу, которая вызывает /visits/:id с вызовом AJAX для заполнения полей, и это позволит мне избежать развращения моего ресурса, управляемый API с определенным для браузера маршрутом. Или есть какой-то лучший вариант? Что такое лучшая практика и почему?

Answer 1

В REST нет смысла создавать дополнительные ресурсы просто для выполнения стандартизованных действий. Каждый, кто знает протокол HTTP, знает, что ваш объект посещения должен быть доступен для редактирования через запрос PATCH с использованием diff, который вы хотите применить, или через запрос PUT, который заменяет весь ресурс новым. Зачем создавать настраиваемое и нестандартное действие редактирования с помощью POST, что вам придется документировать и объяснять всем, как это работает?

В этом смысле, я бы сказал, что ваш лучший вариант - статическая страница HTML, которая управляет вашим API, используя GET on/посещения /: id, чтобы заполнить поля и использовать отредактированный контент для замены/посещения/: id с PUT при отправке.

Однако имейте в виду, что нет ничего плохого в том, что в вашем API существует маршрут, специфичный для браузера, если вы уважаете заголовок Accept, отправленный клиентом. На моих API-интерфейсах иногда я получаю несколько маршрутов, возвращающих дружественное пользователю представление ресурса, когда запрос выполняется с использованием заголовка Accept: text/html, поэтому это простой способ иметь встроенный клиент-администратор, и API можно легко изучить с помощью браузер. В REST единственная разница между API и WEB-страницей заключается в том, что первая возвращает представление в формате, удобном для машин, а второе - представление, которое вы ожидаете от браузера в дружественном для человека документе. Предполагается, что у обоих из них есть ссылки и/или формы с указаниями о том, как редактировать ресурс.