Представление интерфейса веб-сервиса REST клиентам

Question

Один из ресурсов в моем веб-сервисе RESTfull, который выполняет операцию поиска, имеет множество критериев / параметров.

В текущей реализации этот критерий поиска передается как словарь с мнемоникой параметра в качестве ключей.,Например,

{'fieldl_greater_equal' : <value>,
 'field2_like' : <value>,
  ...}

Вопросы:

Каков наилучший способ представить список разрешенных мнемоник и разрешенных значений для каждого мнемоника (т. Е. Интерфейса системы) моим клиентам?

Должен ли я переместить эти мнемоники в inurl-параметры?

Как сделать такой ресурс легко расширяемым?

Любые предложения и предложения о том, как такая система должна быть реализована?

Web-сервис реализуется на Python.

Answer 1

Во-первых.«поиск» может означать почти все.Это помогает очень и очень четко определить, какой вариант использования для вашего запроса GET.

У вас есть три основных варианта «поиска».

• Строка запроса.?param1=this&param2=that

• Фрагмент.#param1=this&param2=that

• Элемент пути URL./this/that

Элемент пути - это то, что вы используете, когда «поиск» действительно использует первичные ключи для идентификации ресурса.Пути не меняются.Это идентичность ресурса больше, чем какой-то «поиск».

Фрагмент очень гибкий, но также живет на границах обработки RESTful URI.Вам, вероятно, следует избегать его использования.

Строка запроса - это то, о чем думает большинство людей, когда они думают о «поиске» вместо «идентификации» ресурса.

Однако компоненты URL-адреса,могут быть довольно сложные вещи.Я использовал синтаксис, такой как /in;param1=this;param2=that/ в URL, чтобы обеспечить более гибкую идентификацию ресурсов.Мы заявляли, что URI определенно (и всегда) будет определять местоположение ресурсов.«В» означает включать.У нас было «ex» для исключения.

Я стараюсь избегать использования ?param1=this&param2=that строки запроса для идентификации ресурса.Я думаю, что он должен использовать его для номеров страниц и других вещей, которые не были необходимы для определения ресурсов.

Независимо от того, что вы делаете, вам необходимо предоставить список разрешенных param имен и их интерпретацию.Это «метаданные», и вы можете реализовать метаданные REST-запросов.

Вы определяете некоторые API-интерфейсы "/ api" или "/ meta", которые предоставляют информацию об URI, параметрах и о том, как все это сочетается.

Answer 2

Одним из способов описания веб-службы REST является предоставление WADL , описывающего, как можно получить доступ к службе. Для описания допустимых значений вы можете использовать какое-то определение схемы (JSON или XML), которое позволяет определять их перечисления.

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