REST API 设计：一个具有 if/else 逻辑的端点或两个基于角色的独立端点

Question

我有一个 API 设计/版本控制难题。假设我有一个端点/api/customers可以获取所有客户（忽略分页）。但是有一个转折点：如果常规user访问此端点，他们只会获得该用户创建的客户，而没有其他人（我可以检查访问令牌和子字段以确定谁发送了请求）。其他用例：如果admin访问此端点，他们应该获得所有客户，无论是谁获得了他们。

现在我的问题是从 API 设计的角度来看：if/else在 API 控制器本身内进行角色检查以确定我是返回所有（管理员）客户还是特定（用户）客户，或者我应该区分用户的端点和行政？即所有客户的管理员只有端点/api/admin/customers，普通用户仍然可以访问他们的/api/customers?

Answer 1

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

例如，学术论文的“作者首选版本”是一个其值随时间变化的映射，而到“会议 X 会议记录中发布的论文”的映射是静态的。这是两种不同的资源，即使它们在某个时间点都映射到相同的值。这种区别是必要的，以便可以独立地识别和引用这两种资源。软件工程中的一个类似示例是在引用“最新修订版”、“修订版号 1.2.7”或“Orange 版本中包含的修订版”时单独标识版本控制的源代码文件。——菲尔丁，2000

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

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

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

在 HTTP/2 中，服务器推送可能会减轻您的一些往返痛苦。

共享缓存的规则应该防止您将 Alice 的“我”资源视图发送给 Bob，反之亦然，但了解各种标头的含义很有用，这样您就不会无意中禁用该保护。

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

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

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

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