Разработка правильных REST URI

Question

У меня есть компонент Java, который просматривает набор папок (ввод / обработка / вывод) и возвращает список файлов в формате JSON.

REST URL для того же:

GET http://<baseurl>/files/<foldername>

Теперь мне нужно выполнить определенные действия с каждым из файлов, такие как проверка, обработка, удаление и т. Д. Я не уверен, что лучше всего создать URL-адреса REST для этих действий. Поскольку это прямое манипулирование файлами, у меня нет уникального идентификатора для файлов, кроме их путей. Поэтому я не уверен, что следующий URL является хорошим:

POST http://<baseurl>/file/validate?path=<filepath>

Редактировать: в идеале мне бы хотелось использовать что-то вроде / file / fileId / validate. Но единственным уникальным идентификатором для файлов является его путь, и я не думаю, что смогу использовать его как часть самого URL.

И, наконец, я не уверен, какой HTTP-глагол использовать для таких пользовательских действий, как validate.

Заранее спасибо!

С уважением, Ананд

Answer 1

Когда вы реализуете маршрут, такой как http: /// file / validate? Path , вы кодируете действие в своем ресурсе, которое не является желаемым эффектом при моделировании службы ресурсов.

Выможет сделать следующее для операций чтения

GET http://api.example.com/files вернет все файлы в качестве URL-ссылки, например

http://api.example.com/files/path/to/first
http://api.example.com/files/path/to/second
...

GET http://api.example.com/files/path/to/first вернет результаты проверки файла (я использую JSON для удобства чтения)

{
   name : first,
   valid : true
}

Это была простая часть только для чтения.Теперь к операциям записи :

DELETE http://api.example.com/files/path/to/first, конечно, удалит файл

Моделирование обработки файла является сложной частью.Но вы можете смоделировать это как ресурс высшего уровня.Таким образом:

POST http://api.example.com/FileOperation?operation=somethingweird создаст виртуальный ресурс обработки файлов и выполнит операцию, заданную параметром URL 'операция'.Моделирование этих файловых операций как ресурсов дает вам возможность выполнять операции асинхронно и возвращать результат, который дает дополнительную информацию о процессе операции и т. Д.

Вы можете взглянуть на Amazon S3REST API для дополнительных примеров и идей о том, как моделировать ресурсы.Я настоятельно рекомендую прочитать RESTful Web Services

Answer 2

REST требует единого интерфейса, что в HTTP означает ограничение себя GET, PUT, POST, DELETE, HEAD и т. Д.

Один из способов проверки правильности каждого файла в RESTful - это рассматривать проверку достоверности не как действие, выполняемое над файлом, а как отдельный ресурс:

GET /file/{file-id}/validity

Это может вернуть простое значение True / False или, возможно, список конкретных нарушений ограничений. Идентификатором файла может быть имя файла, целое число файлов, путь в кодировке URL или, возможно, незашифрованный путь, например:

GET /file/bob/dir1/dir2/somefile/validity

Другой подход - запросить список недействительных файлов:

GET /file/invalid

И еще один способ предотвратить добавление недопустимых файлов в вашу службу, т. Е. Когда ваша служба обрабатывает запрос PUT с неверными данными:

PUT /file/{file-id}

отклоняет его с HTTP 400 (неверный запрос). Тело ответа 400 может содержать информацию об определенной ошибке.

Обновление: чтобы удалить файл, вы, конечно, использовали бы стандартный HTTP REST глагол:

DELETE /file/{file-id}

Чтобы «обработать» файл, это создает новый файл (ресурс) из загруженного? Например, Flickr создает несколько разных файлов изображений для каждого загружаемого файла, каждый из которых имеет свой размер. В этом случае вы можете PUT входного файла и затем запустить обработку, ПОЛУЧЯ соответствующий выходной файл:

PUT /file/input/{file-id}     
GET /file/output/{file-id}

Если обработка не является почти мгновенной, вы можете генерировать выходные файлы асинхронно: каждый раз, когда новый входной файл помещается в веб-службу, веб-служба запускает асинхронную операцию, которая в конечном итоге приводит к тому, что выходной файл становится создано.

Answer 3

Теперь мне нужно выполнить определенные действия с каждым из файлов, такие как проверка, обработка, удаление и т. Д. Я не уверен в наилучшем способе создания URL-адресов REST для этих действий. Поскольку это прямое манипулирование файлами, у меня нет уникальных идентификаторов файлов, кроме их путей. Поэтому я не уверен, что следующий URL является хорошим: POST http:///file/validate?path=

Это не так. /file/validate не описывает ресурс, он описывает действие. Это означает, что он функциональный, а не RESTful.

Редактировать: В идеале мне бы хотелось использовать что-то вроде /file/fileId/validate. Но единственным уникальным идентификатором для файлов является его путь, и я не думаю, что смогу использовать его как часть самого URL.

О да, вы можете! И вы должны сделать именно это. За исключением этой финальной части validate; это никоим образом не ресурс, и поэтому не должно быть частью пути. Вместо этого клиенты должны POST-сообщение к файловому ресурсу с просьбой подтвердить себя. К счастью, POST позволяет отправить сообщение в файл, а также получить его обратно; он идеально подходит для такого рода вещей (если вместо этого не существует существующего глагола, будь то стандартный HTTP или одно из расширений, таких как WebDAV).

И, наконец, я не уверен, какой глагол HTTP использовать для таких пользовательских действий, как validate.

POST, с действием, которое нужно выполнить, определяется содержимым сообщения, которое было POST отправлено ресурсу. Пользовательские действия «сделать что-то нестандартное» всегда сопоставляются с POST, когда они не могут быть сопоставлены с GET, PUT или DELETE. (Увы, умный POST не очень доступен для обнаружения и поэтому вызывает проблемы для принципа HATEOAS, но это все же лучше, чем нарушение основных принципов REST.)