10

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

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

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

创建 Blueprint API 文档时如何在 URL 中格式化基于哈希的参数？

我希望键名是可变的，因为它可以是源数据中的任何字段。这行得通吗？

## 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]

4

2 回答 2

5

恐怕 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

这种方法有两个注意事项：

  • 您只能为参数指定一个字段名称和字段值。如果你想要更多的字段参数，你必须扩展 URL。
  • 您必须更改我认为您不想更改的 API url。

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

于 2015-04-26T19:38:17.377 回答
3

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中指定这些，因为我认为不支持“动态键”，而且我认为大多数工具（还）无法处理它。

可能值得一问。

于 2015-04-27T09:28:31.523 回答