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

Question

我正在使用 Api 蓝图为 RESTful 搜索 API 开发 api 文档。我希望能够将过滤器传递给 API 这样我就可以 assemble:

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_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 Templates standard. There are ways to express and expand arrays (see 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 中指定它们，因为我认为不支持“动态键”，而且我认为大多数工具都无法处理它（还).

What is a 2-dimensional key-value format that Api Blueprint can understand?