当端点非常相似时，路径参数与查询参数

Question

我目前正在开发一个公开不同端点的 REST API。

这种端点的一个例子是

/users/{userId}/transactions/type/{transactionType}/all

此端点returns用户特定交易类型的所有交易列表。

我还有一个端点，用于从用户检索特定类别的所有交易，该端点将访问该端点

/users/{userId}/transactions/category/{categoryId}/all

我的问题是这是一种好方法还是只有一个端点和可选的查询参数更好？

例如

/users/{userId}/transactions/all?categoryId={id}&transactionType={type}

/users/{userId}/transactions/all?categoryId={id}

/users/{userId}/transactions/all?transactionType={type}

/users/{userId}/transactions/all

后者的好处是您可以按类别和类型过滤您的交易，而不仅仅是一个。但这是一个好的设计还是有更好的方法？

Answer 1

是的，使用查询参数来过滤交易是一种很好的方法。但是为了遵循 REST 的思想，如果您更改端点会更好。

来自

/users/{userId}/transactions/type/{transactionType}/all

到

/users/{userId}/transactions?transactionType={transactionType}

您可以从端点阅读以下内容：查询将为具有值 userid 的用户 return 所有具有 transactionType 的交易。因此，将由查询 return 编辑的值应保留在端点的末尾，并且所有过滤器都是查询 parameters.In 你的情况是查询 return 事务，因此事务在末尾并且然后查询参数。

并且您不需要在 REST 端点中使用单词 'all'。

/users/{userId}/transactions?categoryId={id}&transactionType={type}

Answer 2

除了您的标识符应符合 RFC 3986.

之外，REST 不提供有关 URI 设计的指导。

/x/y/z
/x?y=z

这两个标识符都很好。

具有 application/x-www-form-urlencoded 键值对的 URI 具有 Web 浏览器具有 HTML 表单处理标准的优势。该表格充当一种 URI Template.

当您有标识符层次结构要导航时，路径段很方便，因为 URI 标准包括 relative resolution 和点段。

在 REST 中，标识符在功能上是不透明的 - 通用客户端不会从 URI 中提取任何语义信息。这使服务器可以自由地将它想要的任何信息编码到标识符中。

也就是说，对于你自己的资源，你可以选择任何你喜欢的URI设计。最常见的选择集中在易于路由（在您碰巧选择的任何服务器实现中）和符合本地设计标准（这样，URI 很像变量名——compiler/interpreter不在乎，但是执行代码审查的人确实在乎）。

见Stefan Tilkov's 2014 talk。

当端点非常相似时，路径参数与查询参数

Path params vs query params when the endpoints are very similar

java

api

rest

spring

web-services