api - REST API 最佳实践 : Where to put parameters?

Question

关闭。这个问题需要多问 focused 。目前不接受答案。

已关闭 8 年前。

已锁定。这个问题及其答案是 locked因为这个问题是题外话，但却具有历史意义。目前不接受新的答案或互动。

REST API 至少可以通过两种方式拥有参数:

1. 作为 URL 路径的一部分(即 /api/resource/parametervalue )
2. 作为查询参数(即 /api/resource?parameter=value )

这里的最佳实践是什么？何时使用 1 和何时使用 2 有什么一般准则吗？

现实世界示例:Twitter 使用查询参数来指定间隔。 (http://api.twitter.com/1/statuses/home_timeline.json?since_id=12345&max_id=54321)

将这些参数放在 URL 路径中是否会被认为是更好的设计？

Answer 1

如果有记录的最佳实践，我还没有找到。不过，以下是我在确定在 url 中放置参数的位置时使用的一些准则:

可选参数往往更容易放入查询字符串中。

如果您想在参数值与现有资源不对应时返回 404 错误，那么我倾向于使用路径段参数。例如/customer/232 其中 232 不是有效的客户 ID。

但是，如果您想返回一个空列表，那么当找不到参数时，我建议使用查询字符串参数。例如/contacts?name=dave

如果参数影响 URI 空间的整个子树，则使用路径段。例如语言参数 /en/document/foo.txt 与 /document/foo.txt?language=en

我更喜欢在路径段中使用唯一标识符，而不是在查询参数中。

URI 的官方规则可在此 RFC 规范 here 中找到。 。还有另一个非常有用的 RFC 规范 here定义参数化 URI 的规则。