带有身份验证的 RESTful API URL 设计

Question

我的数据模型是这样的：

User: id, email, hashed_password
Item: id, name, color
UserItem: user_id, item_id, rating

我想编写一个 RESTful API 来获取这些资源。身份验证是通过 OAuth 2 提供的，带有 JWT 令牌（包含记录的用户 ID）。

第一种方法

端点

URL 结构的第一个想法是（我在还没有身份验证时选择的那个）：

/items/{item_id}
/users/{user_id}
/users/{user_id}/items/{item_id}

在这种情况下，ID 为 1 的用户可以使用：

• GET /users/1获取自己的信息；
• GET /users/1/items获取自己的物品（有评分）；
• GET /items 获取他们可以添加到收藏中的所有项目。

分析

我认为这个解决方案很清晰，但也不优雅。

好：

• 您可以轻松获取其他用户信息（如果他们可用）；
• 端点和数据模型之间的一对一关系。

不好：

• 较长的网址；
• 存在冗余（为什么 GET /users/1/items 在令牌中已经有关于 id 1 的信息？）。

第二种方法

端点

鉴于您可以从令牌中提取用户 ID，因此结构也可以更简单：

/items/{item_id}
/users/{user_id}

在这种情况下，ID 为 1 的用户可以使用：

• GET /users/me获取自己的信息；
• GET /items?class=owned获取自己的物品（带评分）；
• GET /items?class=all 获取他们可以添加到收藏中的所有项目。

分析

这个解决方案有点混乱，但可能更优雅。

好：

• 较短的网址；
• 减少冗余（GET /items 获取您自己的项目）。

不好：

• 仅表示模型 UserItem（即使在这种情况下，获得没有评级的项目可能几乎毫无意义，如果用户尚未添加它，则可以将其设置为 null）；
• 获取其他用户的项目并不简单（可能类似于GET /items?user=3？）。

结论

老实说，我不知道在这种情况下最佳做法是什么。我觉得这两个都有点不对劲。也许有一种我没有看到的混合方法？

你会如何组织这样的模型？

Answer 1

您可以查看 HAL 之类的格式。 HAL 为您提供了一种描述特定资源（项目）的方法，并允许您创建指向这些资源的多个集合。

这意味着单个项目可以托管在 /items/xyz，但项目可以同时是 /user/a/items 和 /items 集合的一部分。

我在一个超媒体客户端上做了很多工作：https://github.com/badgateway/ketting。这不仅仅是一个广告，还有其他选择，但我们可能会非常适合您的 API 设计方法。

但无论您使用的是哪种客户端，这样的系统都可以避免通过多个端点检索相同项目的问题。单个项目有一个规范的 url，如果系统设计得好，您只需检索一次。

集合只是指向属于该集合的资源（项目）的链接列表。它们指向项目，但不“包含”，就像常规超链接一样。