Question

我正在使用Api Blueprint为RESTful搜索API开发api文档。我希望能够将过滤器传递给API，以便我可以组装：

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

根据这个问题，我使用的是百分比编码的方括号，但与此问题不同，我们无法描述每个可能的关键名称：

我希望密钥名称是可变的，因为它可以是源数据中的任何字段。这有用吗？

## 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]不匹配

Answer 1

我担心API Blueprint和Apiary还不允许这种动态URL定义。

API Blueprint和Apiary仅允许RFC 6570

中定义的URI模板

根据RFC

，以下URI模板无效

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

您可以更改网址以定义如下内容：

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

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

这种方法有两点需要注意：

如果您有任何功能，请在http://support.apiary.io开始功能请求。

Answer 2

API蓝图使用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中指定那些，因为我认为不支持“动态密钥”，我认为大多数工具都不会处理它（尚未）。