REST URI и операции над объектом, которые можно комментировать, маркировать, оценивать и т. Д.

Question

Я занимаюсь исследованием веб-API для своей компании, и похоже, что мы можем реализовать RESTful. Я прочитал пару книг об этом сейчас («RESTful веб-сервисы» О'Рейли, которые кажутся наиболее полезными) и придумали следующий набор URI и операций для объекта, который можно комментировать, отмечать и оценивать. ,

Неважно, что это за объект, так как этот сценарий применим ко многим вещам в сети, но ради аргумента скажем, что это фильм.

Некоторые из них, кажется, подходят вполне естественно, но другие кажутся немного вынужденными (особенно рейтинг и пометка), так есть ли у кого-нибудь какие-либо предложения о том, как их можно улучшить? Я перечислю их с URI, а затем с поддерживаемыми глаголами, и то, что я предлагаю, они будут делать.

/movies

GET = Список фильмов

/movies/5

GET = Получить фильм 5

/movies/5/comments

GET = Список комментариев к фильму 5

POST = Создать новый комментарий к фильму 5

/movies/5/comments/8

GET = Получить комментарий 8 к фильму 5

POST = Ответить на комментарий 8 к фильму 5

PUT = Обновить комментарий 8 к фильму 5

/movies/5/comments/8/flag

GET = Проверить, помечены ли фильмы как неподходящие (404, если нет)

PUT = отметить фильм как неподходящий

/movies/5/rating

GET = Получить рейтинг фильма

POST = Добавить пользовательский рейтинг фильма к общему рейтингу

Редактировать: я предполагаю, что объект фильма будет содержать свой рейтинг в качестве свойства, поэтому я не ожидаю, что здесь будет использован метод GET. URI действительно существует, так что рейтинг может быть отдельным ресурсом, который можно обновить с помощью глагола POST. Я не уверен, что это лучший способ сделать это, но я не могу придумать лучшего

/movies/5/tags/tagname

GET = Проверить, помечен ли фильм с помощью tagname (404, если нет; но если он помечен именем тега, должен ли он возвращать фактический ресурс тега путем перенаправления на что-то вроде /tags/tagname?)

PUT = Добавить тег тег к фильму, создав ресурс тега /tags/tagname, если требуется

DELETE = Удалить тег tagname из фильма, удалив ресурс тега tags/tagname, если после этого удаления ничего не помечено

---

Обратите внимание, что это не будут полные URI, например, URI для отображения фильмов будет поддерживать фильтрацию, разбиение по страницам и сортировку. Для этого я планировал что-то вроде:

/movies/action;90s/rating,desc/20-40

Где:

действие; 90-е - набор критериев фильтра, разделенных точкой с запятой

рейтинг, desc - порядок и направление сортировки

20-40 - это диапазон индексов предметов для получения

Есть ли комментарии по поводу этой схемы API?

---

Редактировать # 1

Этот пост становится довольно длинным! Прочитав некоторые ответы и комментарии, я планирую внести следующие изменения:

Теги будут обрабатываться как группа, а не по отдельности, поэтому они будут по адресу:

/movies/5/tags

GET = список тегов

POST = Объединение указанных тегов и существующих тегов

PUT = Заменить любые текущие теги указанными тегами

DELETE = Удалить все теги

Я все еще действительно не знаю, как обрабатывать пометку комментария. Один из вариантов заключается в том, что вместо POSTing к комментарию, отвечающему на него, объект комментария будет включать в себя своего родителя, чтобы его можно было поместить в общий URI, т.е.

/movie/5/comment

POST = Создать новый комментарий (который может быть ответом на комментарий)

Я мог бы затем использовать POST для комментария, чтобы пометить его. Но это все еще не совсем правильно.

/movie/5/comment/8

POST = Флаг комментария

Answer 1

Большая часть того, что у вас есть, выглядит хорошо. Я видел только пару странных вещей. Когда я соединяю свои URL, я стараюсь следовать этим четырем принципам.

кожура лука

Если вы сделаете R в REST действительно ресурсом, тогда URL ресурса должен быть в состоянии откинуться назад и при этом иметь смысл. Если это не имеет смысла, вы должны переосмыслить, как организовать ресурс. Так что в случае ниже, каждый имеет смысл. Я либо просматриваю конкретный предмет, либо коллекцию предметов.

/movies/horror/10/
/movies/horror/
/movies/

Мне кажется смешным следующее, потому что flag не ресурс, это свойство movie.

/movies/5/comments/8/flag -> Funny
/movies/5/comments/8/     -> Gives me all properties of comment including flag

Определение вида

Последняя часть URL описывает, как показать ресурс. URL /movies/horror/ говорит мне, что у меня будет коллекция фильмов, очищенных от ужаса. Но могут быть разные способы отображения этой коллекции.

/movies/horror/simple
/movies/horror/expanded

Простым представлением могут быть только заголовок и изображение. Расширенное представление даст гораздо больше информации, например, описание, резюме и оценки.

Помощники

После того, как ресурс был ограничен и выяснено правильное представление, параметры строки запроса используются, чтобы помочь пользовательскому интерфейсу с мелочами. Наиболее распространенные параметры строки запроса, которые я использую:

p => Page
n => number of items to display
sortby => field to sort by
asc => sort ascending

Так что я мог бы получить URL-адрес вроде

/movies/horror/default?p=12&n=50&sortby=name

Это даст мне список movies, ограниченный фильмами ужасов с видом по умолчанию; начиная со страницы 12, с 50 фильмами на странице, где фильмы отсортированы по названию.

Действия

Последнее, что нужно, это ваши действия на ресурсе. Действие основано либо на коллекции, либо на элементе.

/movies/horror/
GET -> Get resources as a list
POST -> Create, Update

/movies/horror/10/
GET -> Get resource as item
POST -> Update

Надеюсь, это поможет.

Answer 2

Я не согласен с редактированием. Запросы должны определяться строками запросов согласно посту Мартина Лаармана. i.e.:

/movies?genre=action&timeframe=90s&lbound=20&ubound=40&order=desc

Answer 3

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

Например, рейтинг может быть частью ответа / movies / 5

<movie>
   <title>..</title>
   ..
   <rating url="movies/ratings/4">4</rating>
   <tags>
      <tag url="movies/tags/creative">creative</tag>
      ...

Удаление тега просто означает публикацию вышеуказанного ответа без этого тега.

Также запросы должны идти в переменных URL, я считаю: /movies/?startsWith=Forrest%20G&orderBy=DateAdded

Answer 4

Это не ОТДЫХ.

REST API не должен определять фиксированные имена ресурсов или иерархии (очевидная связь клиента и сервера). Серверы должны иметь свободу управления своим собственным пространством имен. Вместо этого позвольте серверам инструктировать клиентов о том, как создавать соответствующие URI, например, в HTML-формах и шаблонах URI, определяя эти инструкции в типах медиа и связях. [Ошибка здесь подразумевает, что клиенты принимают структуру ресурса из-за внеполосной информации, такой как специфичный для области стандарт, который является ориентированным на данные эквивалентом функциональной связи RPC].

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

Answer 5

@ Нельсон Лакет:

Использование методов HTTP в том виде, в каком они фактически определены, дает вам уверенность в том, что выполнение GET для чего-либо на веб-сайте или в службе не сожрет ваши данные или иным образом повлияет на них. В качестве примера (указан в RESTful Web Services ) Google Accelerator ожидает такого поведения - как указано в FAQ - и предположительно другие службы тоже .

Также вы получаете Идемпотентность бесплатно. То есть выполнение GET, DELETE, HEAD или PUT для ресурса более одного раза - это то же самое, что выполнение этого только один раз. Таким образом, если ваш запрос терпит неудачу, все, что вам нужно сделать, это запустить его снова.

Answer 6

Это потрясающий первоначальный черновик для спецификации REST API. Следующим шагом будет указание ожидаемых кодов возврата (как вы сделали с «404 Нет доступных тегов»), приемлемых типов содержимого и доступных типов содержимого (например, HTML, JSON). Выполнение этого должно выявить любые дополнительные трещины, которые вам нужно будет выбить.

Answer 7

Судя по моему пониманию ROA (я только о пятой главе веб-сервисов RESTful), мне это нравится.

Answer 8

Имеет смысл для меня. Хотя я не понимаю, почему использовать разные методы HTTP лучше, чем просто использовать обычный GET / POST и использовать структуру URL, например:

movies/10/edit
movies/10/ratings/add
movies/10/ratings/10/reply
movies/10/ratings/10/edit
movies/10/tags
movies/10/tags/add
movies/10/tags/10/remove

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

:)

Если я что-то упустил (ранее не имел дело с REST), пожалуйста, дайте мне знать, почему лучше использовать методы HTTP (таким образом, ограничивая ваши операции и не чувствуя себя «правильно» с определением разницы между PUT и POST) по обычному методу.

В ответ на комментарии

Подождите, так ... HTTP определяет четыре глагола; но также определяет способность называть наши URI так, как мы хотим. Поэтому вместо добавления глагола в конце URI:

movies/10/edit

Мы просто соответствуем глаголам, определенным базовым протоколом. Это звучит глупо для меня. Мне нужно было бы немного убедительно убедить, что это лучший способ сделать что-то, чтобы изменить свое мнение. Это звучит немного "причудливо" для меня; например, когда вышел AJAX, и все стали использовать XML для представления данных (что замедляет работу систем из-за времени, необходимого для анализа и принудительной обработки) и потребляет гораздо большую пропускную способность, чем необходимо), и теперь мы застряли с SOAP.

Как лучше ограничить ваш глагол Vocab?

Я вовсе не хочу казаться враждебным; но, как я уже сказал, мне не нравятся причуды, и для меня это выглядит так, если кто-то не может дать мне повод не думать так.

В ответ на комментарии # 2

У меня вообще нет проблем с XML. Как язык разметки. Как в расширяемом языке разметки . Если вы посмотрите на Wikipedia , вы увидите, что использование XML в качестве структуры данных выходит за рамки его предполагаемого использования. Не поймите меня неправильно - если бы все вещи всегда использовались так, как это было задумано при его создании, мы бы никогда не развивались. Но использование XML в двоичном формате для передачи данных из программы в программу бессмысленно.

• XML-документы увеличивают размер фактических данных с помощью удобочитаемого синтаксиса, когда в большинстве случаев используется XML, люди фактически никогда не читают и не редактируют контент сами.
• XML требует времени и памяти для загрузки, анализа и приведения значений в атрибутах и ​​узлах в формат, понятный компьютеру.

Использование чего-то вроде JSON (хотя это и не двоичный формат - но это формат, который может быть выполнен на виртуальной машине JS) намного лучше для производительности и выделения памяти в AJAX - и насколько это возможно в SOAP я просто поражаюсь, что протокол «компьютер-компьютер» будет написан на языке, специально разработанном для редактирования человеком.

Возьмем, к примеру, Magento (платформа электронной коммерции). Он использует один или несколько файлов конфигурации XML на модуль. Но чтобы сделать их и без того очень медленное приложение (мне нравится Magento BTW, но оно НАМНОГО медленнее, чем нужно), они пишут код, который сериализует массив, созданный с использованием XML-файлов конфигурации, чтобы он мог загружай быстрее. Если они только что сделали что-то вроде:

<?php
    $this->SetConfig(array(
        "Database" => array(
            "host" => "localhost")));
?>

(этот файл конфигурации будет "обязательным" из метода класса конфигурации, который создается для каждого модуля)

Вместо этого дерьма XML приложение наверняка ускорится; и уменьшит количество «кода оптимизации», которое они должны были написать.

Да, XML - это причуда. Да, XML чрезмерно используется в ситуациях, в которых он никогда не должен использоваться. XML, безусловно, имеет свое место (XHTML, механизмы шаблонов), но НЕ для хранения файлов конфигурации, файлов данных или взаимодействия между компьютерами.

Что касается REST, я неправильно понял, что это было. Это выглядит интересно, хотя; Я посмотрю на это больше, хотя. Но из-за таких увлечений, как XML, я не решаюсь использовать эти новые методы.