REST API 设计 : one endpoint with if/else logic or two separate role based endpoints

Question

我有一个 API 设计/版本控制难题。
假设我有一个端点 /api/customers获取所有客户(忽略分页)。不过有一个转折点:如果是普通的 user访问这个端点，他们只会得到由该用户创建的客户，而没有其他人(我可以检查访问 token 和子字段以确定谁发送了请求)。其他用例:如果 admin访问此端点，他们应该获得所有客户，无论是谁获得了他们。

现在我的问题是从 API 设计的角度出发:拥有 if/else 是否更好？ API Controller 本身内的角色检查以确定我是返回所有(管理员)客户还是特定(用户)客户，还是应该区分用户和管理员的端点？ IE。所有客户的仅限管理员端点将是 /api/admin/customers普通用户仍然可以访问他们的 /api/customers ?

Answer 1

在 REST 中，拥有多个共享相同表示的资源是很正常的。

For example, the "authors' preferred version" of an academic paper is a mapping whose value changes over time, whereas a mapping to "the paper published in the proceedings of conference X" is static. These are two distinct resources, even if they both map to the same value at some point in time. The distinction is necessary so that both resources can be identified and referenced independently. A similar example from software engineering is the separate identification of a version-controlled source code file when referring to the "latest revision", "revision number 1.2.7", or "revision included with the Orange release." -- Fielding, 2000

与这种方法完全一致的是，您可能拥有一个用于“所有用户”的资源，以及另一个用于“由 Bob 创建的用户”的资源。

事情变得棘手的情况是您想要使用相同的资源标识符来提供不同的表示。也就是说，当 Alice 查看“我创建的用户”时，她看到的是“Alice 创建的用户”，而当 Bob 查看“我创建的用户”时，他看到的是“Bob 创建的用户”。

一种可能性是让“我创建的用户”重定向到适当的资源。当目标资源不在本地缓存中时，它适用于允许额外往返的“works”值。

在 HTTP/2 中，服务器推送可能会让你免去一些往返的痛苦。

shared caches的规则应该可以防止您将 Alice 对“我”资源的 View 发送给 Bob，反之亦然，但是了解各种 header 的含义很有用，这样您就不会无意中禁用该保护。

在某些“读取您自己的写入”设置中拥有不同的资源可能是一个问题，因为缓存不会知道不安全的请求已使两个资源都无效。 Bob 通过 POST 向“我创建的用户”创建了一个新用户，并且相应的缓存条目已失效……但“所有用户”是不同的缓存键，并且不会失效。因此，如果 Bob 查看所有用户 View ，他可能会看到先前缓存的副本，而没有他刚刚在自己的 View 中看到的更改。

在某些情况下，考虑子资源是有意义的。

/api/customers
/api/customers#created-by-Alice
/api/customers#created-by-Bob

但是，如果您试图减少交换的不相关数据的数量，那么这并不合适。