RESTAPI最佳实践：在哪里放置参数？

Question

RESTAPI最佳实践：在哪里放置参数？

RESTAPI至少可以有两种方式的参数：

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错误，则我倾向于使用路径段参数。G./customer/232其中232不是有效的客户ID。但是，如果您想返回一个空列表，那么当找不到参数时，我建议使用查询字符串参数。G./contacts?name=dave如果参数影响URI空间的整个子树，则使用路径段。例如语言参数/en/document/foo.txt对决/document/foo.txt?language=en与查询参数相比，我更喜欢在路径段中的唯一标识符。URI的正式规则在本rfc规范中找到。这里..还有另一个非常有用的rfc规范。这里它定义参数化URI的规则。

Answer 2

这取决于设计。在HTTP上，对于处于静止状态的URI没有规则(主要是它们是唯一的)。通常是关于味觉和直觉的问题.。我采取以下办法：URL路径-元素：资源及其路径元素形成目录遍历和子资源(例如/Item/{id}、/user/Item)。当你不确定的时候，问你的同事，他们是否认为遍历和他们认为在“另一个目录”中最有可能的路径元素是正确的选择。URL参数：当没有真正的遍历时(包含多个查询参数的搜索资源就是一个很好的例子)