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

如何解决在RESTful API中标识单一资源的多种方法

想象一下一个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。还有另一种没有相同缺点的方法吗？我有没有考虑过要让一种设计优于另一种设计？

解决方法

在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>

,

我会选择以下

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

#output

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

/:repository/:branch/commits

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

/:repository/:branch/commits/:sha