Question

想象一下一个HTTP REST API，用于检索Git存储库的提交列表：

/:repository/:branch/commits

我想扩展API以允许通过其标识符（SHA）或其他标准（例如按时间的最后一次提交）来获取有关单个提交的信息。这可以通过使用路径或查询参数以两种不同的方式来实现。

通常将URL参数用作主要资源标识符：

/:repository/:branch/commits/:sha

现在，最新提交的URL可以

/:repository/:branch/commits/latest

这将导致最后一个URL组件被视为特殊标识符或提交SHA。如果“最新”不是有效的提交标识符，但感觉不正确，这将起作用：同一URL组件根据其值具有不同的作用。

另一种替代方法是使用查询参数：

/:repository/:branch/commits?latest或（?latest=true）

在这种情况下，将SHA或其他条件标识为提交完全分开。 /commits API端点变得不对称：根据存在的查询参数，响应具有不同的结构；如果请求了最新提交，则响应为单个对象；否则为数组（例如，未经过滤或未经作者过滤）。返回单对象数组以进行最新提交也感觉不对。

这两种方法均无法产生一致的API。还有另一种没有相同缺点的方法吗？我有没有考虑过要让一种设计优于另一种设计？

Answer 1

在RESTful API中标识单个资源的多种方法

我认为，回顾资源上的原始资料是明智的，请参阅Fielding, 2000

资源是到一组实体的概念映射。...

例如，学术论文的“作者偏爱版本”是一个值随时间变化的映射，而到“在X会议录中发表的论文”的映射是静态的。这是两个截然不同的资源，即使它们在某个时间点都映射到相同的值。区分是必要的，以便可以独立识别和引用这两种资源。来自软件工程的一个类似示例是，当引用“最新版本”，“版本号1.2.7”或“ Orange版本附带的版本”时，分别标识了版本控制的源代码文件。

从概念上讲，对于同一资源使用多个标识符是没有错的

GET /f8b0440e-1d65-4800-9e79-ef01183062da
GET /80871fe0-c414-4ec0-b1b3-2c3f0521e2ab

但是通用组件将不会有任何方式知道哪些标识符引用一个公共资源，哪个标识符引用不同的资源。因此，从客户的角度来看，每个唯一标识符都意味着一个唯一资源。

例如，使使用一个标识符存储的缓存表示形式无效也不会使使用其他标识符的表示形式无效。

这将导致最后一个URL组件被视为特殊标识符或提交SHA。如果“最新”不是有效的提交标识符，但感觉不正确，这将起作用：同一URL组件根据其值具有不同的作用。

相同的URL组件根据其值具有不同的作用这一事实没有错。您只需添加逻辑来区分角色-从根本上讲，此逻辑与您用来将请求发送到正确的处理程序的逻辑没有什么不同。我们解析URI，然后使用发现的数据分支到正确的处理程序。

另一方面，信息不明确的事实意味着我们将度过痛苦的时光，试图确保我们返回正确的表示形式。

答案当然是在URI中添加提示，以使含义不再歧义。您可以通过路径段或根据需要修改查询来做到这一点。

在这种情况下，将SHA或其他条件标识为提交完全分开。 / commits API端点变得不对称：根据存在的查询参数，响应具有不同的结构；如果请求了最新提交，则响应为单个对象；否则为数组（例如，未经过滤或未经作者过滤）。

是的，那又如何呢？ client 不在乎-它只是要求使用给定的标识符表示资源；如何实现取决于您自己。产生表示的代码完全不受影响。您唯一需要添加的部分就是确定端点如何委派要完成的工作的逻辑。

但是，例如，如果您的目标是选择资源标识符，以便可以将逻辑复杂性隐藏在通用路由代码中，那么您可以考虑类似

/:repository/:branch/commits
/:repository/:branch/commits/:sha
/:repository/:branch/latest

或类似的

/:repository/:branch/commits
/:repository/:branch/commits/sha?:sha
/:repository/:branch/commits/latest

或

/:repository/:branch/commits
/:repository/:branch/commits/sha=:sha
/:repository/:branch/commits/latest

或

/:repository/:branch/commits
/:repository/:branch/commits/sha/:sha
/:repository/:branch/commits/latest

这些都是 fine ；您选择最适合您的上下文约束的拼写（例如，如果您希望使用HTML表单来访问您的资源，那么您将对在查询部分使用键值对的设计更感兴趣）。 / p>

Answer 2

我会选择以下

用于资源收集（提交收集）

#output

对于特定资源（特定提交哈希）

/:repository/:branch/commits

由于“最新”不是特定的（结果根据请求时间而异），并且实际上类似于“搜索”或“过滤器”，为此，我将使用查询参数：

/:repository/:branch/commits/:sha

在RESTful API中标识单一资源的多种方法

2 个答案: