RESTful API约定

Question

我有一个API，它在请求时随机生成一个资源。

1. 我可以使用什么样的路径来遵循REST约定？ A-/生成/随机.random-/生成器/随机堆栈C-？
2. 我是否应该将我的所有资源放在一个像/api这样的根目录中，以区别于网页？(例如，我可能想在/generators上显示一个HTML页面)
3. 如果对1的答案类似于选项A或B，那么在/generate中会存在什么？

Answer 1

REST并不关心URI的设计。就REST而言，客户机应该认为URI是不透明的。(与缓存头相比，REST更关心的是确保中间组件能够正确地参与正在完成的工作。)

我有一个API，它在请求时随机生成一个资源。

在休息的背景下，这是一句相当奇怪的话。Resource和representation是REST中的重要术语，不能互换。

我希望您想要的是您的API包含一个资源，它在请求时生成一个随机表示。有点像UUID发生器？

因为REST对URI的拼写没有表达意见，所以您应该回到本地URI设计准则上来。这些建议通常建议资源由名词标识，路径段表示层次结构。

/generators/random

"/generators“很好，因为它表明您正在标识某个集合的一部分资源。“随机”，作为一个形容词，不是很好。下一个有用的步骤可能是问“随机什么？”从你的第一次尝试中猜测，这些可能是合理的选择。

/generators/randomImage
/generators/randomPNG
/generators/image?random
/generators/png?random

REST的部分要点是实现可以与服务分离--源服务器生成的资源的表示可以直接从文件系统加载，或者直接从键值存储中提取，或者通过调用函数或将工作委托给另一个端点来生成。因此，你最好通过什么而不是如何来识别你的资源。

因此，这些选择要好得多，因为它们更好地表达了表示(这是图像的表示，而不是随机图像生成器的表示)。

/images/random
/images/pngs/random

我是否应该将我的所有资源放在一个像/api这样的根目录中，以区别于网页？

也许吧。休息不关心拼写。客户应该只关注你给他们的任何链接，所以重要的是要确保你发布的书签是合理的。有些服务使用不同的主机来区分api资源和文档资源；但许多服务使用前缀路径段。

如果对1的答案类似于选项A或B，那么在/generate中会存在什么？

那里可能什么都没有。集合的成员模式中有一个具有标识符的资源，这一事实绝不意味着集合本身也有一个资源。如果您愿意的话，您可以很高兴地对任何请求进行404；REST的客户端应该导航到已发布的书签并遵循链接--玩猜测-uri游戏是不允许的。

在要由客户端修改资源集合的apis中，一个常见的模式是由集合URI标识一个POST端点，该端点允许客户端在集合中创建新成员。

难道我不是更喜欢传达它是随机产生的东西吗?再次请求它可能不会产生同样的结果吗？

REST组件使用缓存头而不是URI来确定以前获取的表示是否仍然可行。

URI拼写的听众纯粹是人为的。

指导原则是在酷的城市不会变中概述的；您希望继续将相同的URI映射到相同的概念，即使生成表示的底层实现发生了更改。

/images/flowers/flowerOfTheDay
/images/flowers/latest
/images/flowers/random

所以在你的设计中你需要考虑的是图像的随机性是否是这个概念的核心？

REST依赖于作者选择一个最适合所标识概念性质的资源标识符。