什么是Api Blueprint可以理解的二维键值格式？

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}

您可以更改URL以定义类似以下内容:

## 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 模板标准。有多种方法可以表达和扩展数组（请参阅第 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中指定它们，因为我认为不支持“动态键”，而且我认为大多数工具还无法处理它。