Что такое двумерный формат ключ-значение, который может понять Api Blueprint?

Я разрабатываю документацию по API для поискового API RESTful, используя Api Blueprint. Я хотел бы иметь возможность передавать фильтры в API, чтобы я мог собрать:

filter[filtername1]=filtervalue1
filter[filtername2]=filtervalue2

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

Как отформатировать хэш на основе параметров в URL-адресе при создании документа Blueprint API?

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

## Key-Value-Test [/api/v1/keyvaluetest?term={term}&filter%5B{field_name}%5D={field_value}]

+ term
+ filter_field
+ filter_value

Есть ли рекомендуемый формат для такого двумерного массива? Не похоже, чтобы это работало в Dredd, потому что + filter_field на самом деле не соответствует filter[filter_field].


url rest dredd apiblueprint
person danieltalsky    schedule 17.04.2015    source источник

Ответы (2)


arrow_upward
3
arrow_downward

API Blueprint использует стандартные шаблоны URI. Существуют способы выражения и расширения массивов (см. раздел 3.2.1). , однако он ожидает «стандартный подход URI», что означает, что URI будет расширен следующим образом:

/api/v1/keyvaluetest?term=yourterm&filter=filtervalue1&filter=filtervalue2

который является «стандартным» способом создания массивов, за исключением того, что самый популярный веб-язык популяризировал вас еще в 2000-х годах.

Шаблоны предназначены для расширения: дайте ему кучу переменных и строку, и вы получите правильно отформатированную строку. Насколько мне известно, не существует «дикого совпадения» (вставка переменных сопоставления с образцом в определенную позицию в строке).

Единственное решение, которое я могу придумать в области шаблонов URL-адресов, — это использование модификатора расширения (см. составные значения):

/api/v1/keyvaluetest{?keys*}

который с учетом ассоциативного массива значений [(filter%5Bfiltername1%5D, filtervalue1), (filter%5Bfiltername2%5D, filtervalue2) ] должен правильно расширяться.

Однако я не уверен, как указать их в MSON, так как я не думаю, что есть поддержка «динамические клавиши», и я думаю, что большая часть инструментов не справится с этим (пока).

Возможно, стоит спросить.

person Almad    schedule 27.04.2015

arrow_upward
5
arrow_downward

Я боюсь, что API Blueprint и Apiary еще не позволяют использовать такие динамические определения URL.

API Blueprint и Apiary разрешают использовать только шаблоны URI, определенные в RFC 6570.

Следующий шаблон URI недействителен в соответствии с этим RFC

GET /resource?year={year}&month={month}

Вы можете изменить URL-адрес, чтобы определить что-то вроде следующего:

## Key-Value-Test [/api/v1/keyvaluetest{?term,field_name,field_value}]

+ Parameters
    + term: a
    + field_name: b
    + field_value: c

У этого метода есть два предостережения:

  • Вы можете указать только одно имя поля и значение поля для параметров. Если вам нужно больше параметров поля, вам нужно расширить URL-адрес.
  • Вы должны изменить URL-адрес API, который, я не думаю, что вы захотите.

Пожалуйста, начните запрос функции на http://support.apiary.io, если она у вас есть.

person Pavan Kumar Sunkara    schedule 26.04.2015
comment
Вероятно, стоит упомянуть, что @PavanKumarSunkara является разработчиком Apiary. - person David Barker; 26.04.2015
comment
Обратите внимание, что шаблон URI неверен. Вместо ?term={term} вам нужен только {?term}, см. github.com/apiaryio/api-blueprint/blob/master/ - person Zdenek; 27.04.2015
comment
Также по теме – support.apiary.io/knowledgebase/articles/ - person Zdenek; 27.04.2015