用于查找平均值的REST界面

Question

假设我想创建一个REST接口来查找数字列表的平均值。假设一次提交一个号码。你会怎么做？

1. 将号码发布到http://site.com/api/average
2. 如果这是第一个数字，则会返回一个哈希值
3. 将号码发布到http://site.com/api/average/hash ....
4. 获取http://site.com/api/average/hash以找到平均值
5. 删除http://site.com/api/average/hash，因为我们不再需要它了

这是正确的方法吗？有什么建议？

Answer 1

将数字列表视为资源更有意义。假设每个列表的资源URL为/list/{id}，其中{id}是列表ID的占位符。然后：

1. POST /list创建一个新列表，服务器生成一个列表ID（或'hash'），并在响应的/list/{id}标题中指定Location URL。
2. POST /list/{id}在列表中添加了一个数字
3. GET /list/{id}/average返回平均值
4. DELETE /list/{id}删除列表。

GET /list/{id}/average的替代方案是GET /list/{id}将列表作为结构化数据返回，例如XML，包括平均值作为生成的属性。

Answer 2

您所谈论的是将请求表示（数字列表）无状态转换为响应表示（单个数字）。

让我们对您的资源进行分类：

• 无状态 - 请求是无状态的，但资源也是如此。它应该能够接受您的请求，处理它并返回响应而不保持任何内部状态。下面进一步讨论。
• 不太可以缓存 - 我在这里假设你的数字列表永远不会/很少相同。
• 幂等 - 请求没有副作用。这是因为资源是无状态的。

现在让我们检查一下不同的HTTP方法：

• GET - 获取资源的状态。由于您的资源没有状态，因此不适合您的情况。 （幂等，可缓存）
• DELETE - 删除资源或清除其状态。也不适合你的情况。 （不是幂等的，不可缓存的）
• PUT - 用于设置资源的状态（如果不存在则创建它）。 （幂等，不可缓存）
• POST - 用于处理可能修改或不修改资源状态的请求。可以创建其他资源。 （不保证幂等性 - 取决于资源是有状态的还是无状态的，不可缓存的）

正如您在其他答案中看到的那样，POST最常用作“创建”的同义词。虽然这没关系，但POST并不仅限于REST中的“创建”。 Mark Ba​​ker在这里做了很好的解释：http://www.markbaker.ca/2001/09/draft-baker-http-resource-state-model-01.txt（第3.1.4节）。

虽然POST没有完美的语义映射到您的问题，但它是您尝试做的所有HTTP方法中最好的。它还导致了一个简单，无状态且可扩展的解决方案，这是REST的重点。

总之，您的问题的答案是：

• 方法：POST
• 请求：数字列表的表示
• 回复：单个数字的表示（列表的平均值）

虽然这可能看起来像SOAP样式的Web服务调用，但事实并非如此。不要让你对SOAP云的内心反应使用POST方法，并对其施加不必要的约束。

KISS（保持简单，愚蠢）。

Answer 3

您不能只返回哈希或ID，您必须返回URI或URI模板以及字段值。可以作为API一部分的唯一URI是入口点，否则您的API不是REST。

Answer 4

为了最大化REST哲学，我会做以下

执行PUT此操作以指示将根据传递的数字生成哈希的新结构，即不。只是一个“随机”哈希。然后，每个后续帖子都会包含id-hash，并返回已发送数字的返回结果哈希值。然后，当出现get时，您可以缓存结果。

1. PUT    /api/average/{number} //return id-hash
2. POST   /api/average/{id-hash}/{number} // return average-hash
3. GET    /api/average/{average-hash}
4. DELETE /api/average/{id-hash}

然后你可以缓存平均哈希的get，即使你可能以不同的方式获得结果，或者不同的服务器获得相同的平均值。