在 REST API 请求中指定多个项目或所有项目

Question

我正在设计一个 API，我想知道可以指定一个数字或一个项目列表，或者只是指定它是这些项目的 'all' 个值的最佳实践。

例如，假设一个端点 /analyze 允许您针对特定类别分析文档。示例请求可能是：

{
   "documentId": "my-doc",
   "numberOfLines": 100,
   "categories": ["category1", "category2"]
}

表示我想要所有行和所有类别的最佳方式是什么？为相同的值设置多个类型，这样的模式似乎很糟糕：

{
    "documentId": "my-doc",
    "numberOfLines": "all",
    "categories": "all"
}

最好用null或-1之类的东西表示全部。我不喜欢这样，因为如果处理程序错过了该逻辑，它可能会导致错误：

{
    "documentId": "my-doc",
    "numberOfLines": null, //null to mean all
    "categories": null // null to mean all
}

Answer 1

这取决于你想鼓励什么样的行为。如果预期的默认行为是获取所有可能的过滤，我会将这些参数设为可选 - 即

{
   "documentId": "my-doc",
}

将是有效的请求，并且与

的工作方式相同

{
   "documentId": "my-doc",
   "numberOfLines": null, //null to mean all
   "categories": null // null to mean all
}

另一方面，如果您希望客户端默认限制有效载荷，仅在某些特殊用例中有人可能想要所有数据恕我直言，它的文件将引入 "magic words" 例如

{
   "documentId": "my-doc",
   "numberOfLines": "IReallyReallyWantAllData",
   "categories": "IReallyReallyWantAllData"
}

Answer 2

我认为在这里使用字符串 all 没有任何问题。像 Typescript 这样的类型系统和像 JSON Schema 这样的验证系统可以很容易地表达这一点，它比空数组、-1 或 null.

更具描述性。

使用 -1 之类的代码有点像早期的遗留问题，当时保存几个字节很重要，但很难通过观察来判断它的含义。另一个相当明显的选择是星号 *.

Specify a number of items or all items in REST API request