Restful API：管理员和用户范围的最佳实践

Posted 2023-02-16

【中文标题】Restful API：管理员和用户范围的最佳实践

【英文标题】：Restful API: Best practice for admin and user scope

【发布时间】：2022-01-06 08:59:19

【问题描述】：

我正在构建一个 API，用户和管理员可以在其中与相同的数据进行交互，但有不同的需求。 如果用户具有“管理员”角色，他也可以访问管理面板。

例如，让我们看看我们有一个像 Badges 这样的资源。徽章只是您在应用中完成某些操作时的奖励。

GET http://localhost/api/v1/badges

经过身份验证的用户可以调用此端点，它会返回所有徽章的列表（无论是否有徽章）以及进度详细信息。

GET http://localhost/api/v1/badges?user_id=2

使用user_id 参数，我们可以看到其他用户的这些详细信息（如果他允许的话）。

但从管理员范围内，我只需要查看所有徽章的列表，没有成就详细信息（CRUD 操作）。

所以我有两个选择：

创建“管理员”端点：GET http://localhost/api/v1/admin/badges。 添加自定义标题“X-App-Scope”以识别我是管理员还是用户。

我不喜欢第二个，因为我认为我会在同一个端点有很多 if 语句和行为，具体取决于范围。

因为我有很多这样的用例，所以我想确保我的 API 架构能够很好地处理用户/管理员的需求。

你们有什么想法/例子来管理这样的事情吗？

谢谢！

【问题讨论】：

如果你有 X-App-Scope 为什么在 url 中有相同的信息？

这是 2 个不同的想法：url 中的“admin”表示列出徽章的第二个端点，而 X-App-Scope 可用于同一端点 (/v1/badges) 以区分我是否想要简单的徽章列表或包含用户成就详细信息的列表

这是一个公共 API 吗？用户很可能需要经过身份验证才能访问端点，检查经过身份验证的用户是否是管理员，提供不同的结果

我不能这样做，因为用户也可以是管理员，并且在这两种情况下都使用此端点。

对没有成就的版本使用http://localhost/api/v1/badges/simple？

【参考方案1】：

TL;DR：REST 的设计是为了让您在这里使用两个不同的resources。

核心问题是：通用组件，比如浏览器，如何知道你的特殊资源需要添加这个自定义标头？

特别是考虑我向您发送此资源的 URL 副本的情况，仅此而已。您如何知道将客户标头添加到请求中？

另一方面，如果您使用不同的资源与每个受众共享此信息，那么一切都可以正常工作。

【参考方案2】：

我发现保持尽可能简单/清晰的唯一方法是为每个用例创建多个端点：

GET http://localhost/api/v1/badges 获取原始数据中的所有徽章

GET http://localhost/api/v1/users/badges 以转换格式获取所有带有用户统计信息（进度、成就...）的徽章

GET http://localhost/api/v1/users/uuid/badges 以转换格式为指定用户获取所有带有用户统计信息（进度、成就...）的徽章（如果他的个人资料是公开的）

现在我有很多/users/XYZ 端点，但我的代码似乎更易于阅读和维护，而且我真的不需要看代码来猜测将返回什么数据、条件等...

我一直想知道当你有一个管理部分时其他 API 是如何编写的，因为到处都有 /users 并不是真的“漂亮”，而且我在其他任何地方都看不到。