Question

我有一个用于查询多维数据的REST API，其维数可以根据要查询的数据而有所不同，但是在此示例中，我们假设存在COUNTRY，INDICATOR和SEX。用户可以查询任何（或没有）维度，并且可以为每个维度提供一个或多个值：

我需要设计一个可以接受键值对的API，我的原始设计是这样：

但是，最佳实践告诉我，资源应该是路径参数，所以像这样：

然后我找到了矩阵参数，也许是这样：

我心中的问题是，此用例的PATH参数或矩阵参数哪个更好？

Matrix参数不是w3标准的正式组成部分，但它提供了优于使用Path的优势。我可以想到HTTP 304（因为矩阵参数的顺序应该无关紧要），而且我还没有真正看到路径参数用作在路径段（即两个/之间的所有内容）提供一个或多个过滤器的方法。 / p>

Answer 1

我认为您应该问的第一个问题是建模的是什么资源？通过查看您的示例，我现在还不清楚...

您似乎拥有data类型的数据，并且该数据的标识符为providerA。如果这对您的API用户来说是有意义的资源，那么我们很好，但是也许更具描述性？

我知道有些人主张类似于您的第二个示例的“路径参数”，但是对我来说，这种语法确实很奇怪，因为data和providerA之间的路径段没有有效的名称。 ...

路径参数在 URI模板中使用占位符，例如：

中的{name}

/myapi/data/{name}

现在，如果此“数据提供者”资源表示可以由COUNTRY，INDICATOR和SEX进行过滤的内容，我将使用查询参数。

另一方面，如果这些参数确实代表同一资源的不同维度，那么我会将其建模为矩阵参数

/myapi/data;country=UK,FR,DE;sex=M;indicator=X/providerA

（请注意，矩阵参数应该用逗号分隔，而不是用空格编码的空格字符）

我想到了矩阵参数，它们为它们所连接的路径段定义了不同的命名空间。

矩阵参数附加到路径段上，因此下面的示例

/widget;brand=acme/12345/image;type=packshot

...应理解为“品牌acme的小部件12345的packshot类型的图像”。不管REST教条如何，它都比结尾处标记的查询字符串更具可读性和解释性：

/widget/12345/image?brand=acme&type=packshot