时间戳

首页 > 解决方案 > Rest api url 设计异常

api - Rest api url 设计异常

问题描述

我阅读了一些关于更正（干净）用于休息端点的 url 设计的文章和帖子。无论如何，我想讨论或建议我有一些疑问和不清楚的情况。

情况

假设我们有一个服务，它已经注册了用户。管理员可以为每个用户附加一些文本的自定义注释。

我想被告知的问题只是CRUD端点，这可能是微不足道的问题。

我们将有 4 个相关的端点：

POST（创建）
根据一些准则，我们可能会设计如下 URL：
/users/{userId}/notes
并发送包含详细信息的有效负载。这里没有问题

GET（读取）
类似情况：
/users/{userId}/notes
作为响应，我们收到附加到特定用户的注释列表。这里没有问题

更新（更新）
类似情况：
/users/{userId}/notes
作为有效负载服务器接收API包含所有note详细信息的对象。
在这里，我有我的第一个疑问。由于我收到note包含userId:值的对象-我应该严格遵循该URL模式吗？userId在这种情况下是多余的。当然，我也可以PathVariable在有效负载中接收该值，但这是正确的方法吗？同样的情况出现在许多其他CRUD的，这就是为什么我想知道“良好实践”的
API 对象：

{
    "id": 1,
    "userId": 2,
    "text": "Some message"
}

DELETE (delete)
类似情况：
/users/{userId}/notes/{noteId}
实际上删除我只需要noteId信息。正如我认为的那样 -/users/notes/{noteId}就足够了，但这对于DELETE操作来说意味着我会有不同的URL. 情况类似，UPDATE以防万一。

问题

我应该严格遵守 URL 命名约定并使用/users/{userId}/notes吗？什么是简单CRUD操作的好习惯？

标签： apirestclean-architecture

解决方案

您应该查看Webber 2011。

在 REST 中，我们没有“端点”，我们有“资源”。您的资源模型实际上是一组文档，每个文档都有一个唯一标识符，可以读取 (GET) 和写入 (POST/PUT/PATCH)。

域模型中的有用工作是当有人编辑您的资源时发生的副作用。

机器不关心我们对资源标识符使用什么拼写约定，所以我们通常选择一种对人类来说更容易的拼写；通常这意味着标识符与文档的名称密切相关。

由于我收到包含 userId: value- 的注释对象 - 我应该严格使用该 URL 模式吗？

是的。

广义的观点（韦伯在上面链接的谈话中强调）是 HTTP 是一种应用程序协议；只要我们在请求/响应元数据中包含对正在发生的事情的正确描述，通用组件就可以完成有用的工作。

特别是，应用程序具有缓存和缓存失效。如果您正确识别正在更改的资源，缓存可以自动使以前缓存的响应无效。

这就是我们识别请求修改的特定资源的原因之一，而不仅仅是将我们的所有编辑发布到单个通用资源。

我应该严格遵守 URL 命名约定并使用 /users/{userId}/notes 吗？

是的; 实际上，这就像拥有一个包含每个用户的笔记的网页，管理员编辑该网页（添加和删除笔记）。

推荐阅读