REST GET 查询参数建议

Question

我可能会让这变得比它应该的更复杂，但我想知道对于 GET 端点搜索资源的一个或多个实体而言，什么被认为是“良好做法”。我还想让它们“全部”变得容易。对于上下文，我希望人们能够查找与 productId 相关的详细信息，该 productId 可以位于多个（300-400 和不断增长的）位置。对于少数几个位置来说，这并不是一项繁重的操作，但如果用户想要返回所有相关位置，这可能是一个昂贵的 api 调用。

哪一个最好？

使用列表指定哪些位置并假定“所有位置”（如果未提供）

/product/{productId}/search?locations=[1,2,3]

创建一个 allLocations 查询参数以指定用户想要查看所有位置

/product/{productId}/search?allLocations=True

Answer 1

• 首先，您可以使用逗号分隔值而不是数组。

?location=1,2,3

// Then in backend, you can explode/split it which will be much easier.

• 为获得最佳实践，当location 查询参数为空或不可用时，从所有位置获取结果。
• 为了降低 API 调用成本，您可以限制一次选定位置的数量。