Должны ли быть обнаружены параметры обслуживания RESTful?

Преамбула: мое понимание REST в лучшем случае неглубокое, поэтому любые исправления или пояснения к моим вопросам приветствуются.

У меня есть ситуация, когда мне нужен сервис RESTful для отправки произвольного реального положительного числа. Поэтому я предполагаю, что я не должен требовать его в URL-адресе, хотя возвращаемый объект должен быть одним и тем же, и должен использовать параметр вместо этого (или это предположение неверно?).

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

Если нет, я также предполагаю, что параметр должен быть документирован каким-то другим способом, таким образом блокируя (часть) вашего текущего api, который, как я понимаю, нежелателен, так как ресурсы должны быть найдены следующим гипертекстовые ссылки, а не места жесткого кодирования (и параметры в этом случае).

Предполагая, что параметры должны быть доступны для обнаружения, есть ли способ сделать это в tastypie/django?

Ответ 1

"Обнаруживаемая" часть REST обычно относится к новым ресурсам (представленным URI), возвращенным сервером, который ранее не присутствовал. Затем клиентские приложения могут взаимодействовать с этими ресурсами в свободное время.

Например, мое приложение может GET a /library URI, которое возвращает представление того, что в моей локальной библиотеке. Возвращенные данные (закодированные как конкретный тип носителя на основе JSON) могут выглядеть так:

{
   "printedBooks" : "/library/books",
   "audioTapes" : "/library/tapes"
}

Теперь скажем несколько месяцев спустя, я делаю то же самое GET в том же URI, теперь я могу вернуть эту полезную нагрузку:

{
   "printedBooks" : "/library/books",
   "audioTapes" : "/library/tapes",
   "magazines" : "/library/magazines"
}

Теперь появилась новая ссылка на ресурс magazines, который я могу предположительно GET, чтобы узнать, какие журналы доступны. Если мое клиентское приложение не заботится об этом, не имеет большого значения - он просто продолжает использовать два других ресурса, как и раньше. В какой-то момент в будущем я мог бы также подкорректировать поддержку журналов.

Но если я написал какое-то супер-динамическое приложение fancy-shmancy, которое может автоматически адаптироваться к присутствию этого нового ресурса, пользователи приложения смогут использовать его без каких-либо усилий. Не требовалось обновление: сервер предлагал новые функции, и клиент максимально использовал его. Веб-браузеры работают таким образом (хотя и с человеком, управляющим значительной частью "динамизма" ).

К вашему конкретному вопросу о параметрах: они обычно указываются как часть документации API сервера. Я не знаю ни одного API, который автоматически определяет синтаксис параметров, который позволит клиенту быть на 100% общим и адаптируемым.

Хорошо определенный API RESTful стоит на плечах уже указанных технологий, которые он использует (HTTP, URI, согласование типов контента, заголовки и т.д.) и использует вместо этого переопределение. Вот почему я знаю, что я могу, возможно, сделать GET в URI /library/magazines и запросить кодировку на основе JSON, и довольно вероятно, что я добьюсь успеха. Я знаю, что если у меня есть URI для определенного журнала (скажем, /library/magazines/1234), я могу попытаться удалить его, вызвав DELETE на нем, и я узнаю, удалось ли это на основе возвращаемого кода состояния HTTP. Мне не нужно было читать какую-либо документацию или использовать любую магию кодирования для выполнения любой из этих вещей, потому что это действия, уже указанные в HTTP.

Однако, чтобы создать новый журнал POSTing до /library/magazines, мне нужно знать, как должно выглядеть представление данных параметров, независимо от того, передаю ли я эти параметры в URI или внутри тела POST. Это данные, которые должны быть указаны вне диапазона в документации API.

Итак, чтобы подвести итог: серверы RESTful могут отправлять клиентам новую информацию, которую они ранее не видели, и что сердце обнаруживается в REST. Но когда клиент хочет отправить данные на сервер, ему необходимо отправить данные, которые сервер будет понимать и принимать, и которые обычно описаны в документации.