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

Question

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

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

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

How to format hash-based parameters in the URL when creating Blueprint API doc?

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

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

+ term 
+ filter_field 
+ filter_value 

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

Answer 1

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

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

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

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

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

/api/v1/keyvaluetest{?keys*}

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

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

Может быть worth asking.

Answer 2

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

API Blueprint и Пасека позволяет только 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, если у вас есть.