客户端不可编辑属性的资源的 REST API 设计

Question

处理必须通过不向 API 使用者公开的另一种方法修改/更新的资源属性的最佳方法是什么？

例子：

1. 请求用于 X 的新令牌。令牌必须按照一组特定的业务规则/逻辑生成。

2. 在旧汇率到期后请求/刷新货币汇率。该汇率仅供参考，将用于后续交易。

请注意，在上述两个示例中，值是资源的属性，而不是单独的资源。

处理这些类型的场景以及 API 使用者无法控制属性值但需要请求新属性值的其他场景的最佳方法是什么。一种选择是允许 PATCH 在请求正文中具有该特定属性，但实际上并不将属性更新为指定的值，而是运行必要的逻辑来更新属性并返回更新后的资源。

让我们更详细地看一下#1：

请求：

GET /User/1

回应：

{
   "Id": 1,
   "Email": "myemail@gmail.com",
   "SpecialToken": "12345689"
}

作为 API 的使用者，我希望能够请求一个新的SpecialToken，但生成令牌的业务规则对我来说是不可见的。

在 REST 范例中，我如何告诉 API 我需要一个新的/刷新的 SpecialToken？

一个想法是：

请求：

PATCH /User/1
{
   "SpecialToken": null
}

服务器会看到这个请求并知道它需要刷新令牌。后端会用特定算法更新SpecialToken，并返回更新后的资源：

回应：

{
   "Id": 1,
   "Email": "myemail@gmail.com",
   "SpecialToken": "99999999"
}

此示例可以扩展到示例 #2，其中SpecialToken 是资源CurrencyTrade 的汇率。 ExchangeRate 是只读值，API 的使用者不能直接更改，但可以请求更改/刷新：

请求：

GET /CurrencyTrade/1

回应：

{
   "Id": 1,
   "PropertyOne": "Value1",
   "PropertyTwo": "Value2",
   "ExchangeRate":  1.2
}

使用 API 的人需要一种方法来请求新的 ExchangeRate，但他们无法控制值是什么，严格来说是 read only property。

Answer 1

您实际上是在处理资源的两种不同表示形式：一种表示客户端可以通过 POST / PUT 发送的内容，另一种表示服务器可以返回的内容。您没有处理资源本身。

能够更新令牌的要求是什么？令牌有什么用？可以根据用户中的其他值计算令牌吗？这可能只是一个示例，但上下文将推动您最终构建系统的方式。

除非有禁止它的要求，否则我可能会通过使用 PUT“触摸”资源表示来实现令牌生成场景。推测客户端无法更新 Id 字段，因此不会在客户端的表示中定义。

请求

PUT /User/1 HTTP/1.1
Content-Type: application/vnd.example.api.client+json

{
   "Email": "myemail@gmail.com"
}

回应

200 OK
Content-Type: application/vnd.example.api.server+json

{
   "Id": 1,
   "Email": "myemail@gmail.com",
   "SpecialToken": "99999999"
}

从客户端的角度来看，Email 是唯一可变的字段，因此它代表了客户端向服务器发送消息时资源的完整表示。由于服务器的响应包含额外的、不可变的信息，它实际上是在发送同一资源的不同表示。 （令人困惑的是，在现实世界中，您通常不会看到如此清楚地拼写出的媒体类型……它通常被包裹在诸如 application/json 之类的模糊内容中）。

对于您的汇率示例，我不明白为什么客户端必须告诉服务器汇率已过时。如果客户端比服务器更了解汇率的新鲜度，并且服务器正在提供价值，这不是一个很好的服务。 :) 但同样，在这样的场景中，我会像在 User 场景中那样“触摸”资源。

Answer 2

有很多方法可以做到这一点。我想说最好的可能是拥有一个/User/1/SpecialToken 资源，它会提供一个202 Accepted 并带有一条消息，说明该资源无法完全删除，并且每当有人尝试时都会刷新。然后，您可以使用 DELETE、PUT 将其替换为空值，甚至使用 PATCH 直接到 SpecialToken 或 User 的属性。尽管其他人提到了什么，但将 SpecialToken 值保留在 User 资源中并没有错。客户端不必执行两个请求。

@AndyDennie 建议的方法，一个 POST 到 TokenRefresher 资源，也很好，但我更喜欢另一种方法，因为它感觉不像自定义行为。一旦在您的文档中明确说明此资源无法删除并且服务器只需刷新它，客户端就知道他可以通过任何标准化操作将其删除或设置为 null 以刷新它。

请记住，在真正的 RESTful API 中，用户的超媒体表示只会有一个标记为“刷新令牌”的链接，无论执行什么操作，URI 的语义都无关紧要。

Answer 3

我认为您应该考虑将SpecialToken 设为资源，并允许API 的使用者通过POST 对其检索新实例。不知何故，您需要将User 资源链接到SpecialToken 资源。请记住，REST 的核心原则之一是您不应该依赖带外信息，因此如果您想忠于这一点，您需要调查使用链接的可能性。

首先，让我们看看你有什么：

请求：

GET /User/1
Accept: application/json

回复：

200 OK
Content-Type: application/json


{
   "Id": 1,
   "Email": "myemail@gmail.com",
   "SpecialToken": "12345689"
}

虽然此响应确实在对象中包含 SpecialToken 属性，但因为 Content-Type 是 application/json 对于未编程为理解此特定对象结构的客户端实际上没有任何意义。只理解 JSON 的客户端会像其他任何对象一样将其视为对象。让我们暂时忽略它。假设我们的想法是为SpecialToken 字段使用不同的资源；它可能看起来像这样：

请求：

GET /User/1/SpecialToken
Accept: application/json

回复：

200 OK
Content-Type: application/json

{
    "SpecialToken": "12345689"
}

因为我们做了一个GET，所以理想情况下，这个调用不应该修改资源。但是，POST 方法不遵循相同的语义。事实上，很可能向该资源发出POST 消息可能会返回不同的正文。所以让我们考虑以下几点：

请求：

POST /User/1/SpecialToken
Accept: application/json

回复：

200 OK
Content-Type: application/json

{
    "SpecialToken": "98654321"
}

注意POST 消息如何不包含正文。这可能看起来不合常规，但 HTTP 规范并没有禁止这样做，事实上 W3C TAG 说它是 all right：

请注意，即使不在 HTTP 消息正文中提供数据，也可以使用 POST。在这种情况下，资源是 URI 可寻址的，但 POST 方法向客户端指示交互不安全或可能有副作用。

听起来对我来说是正确的。过去，我听说有些服务器在处理POST 没有正文的消息时遇到了问题，但我个人对此没有任何问题。只要确保 Content-Length 标头设置正确，您就应该是金子。

因此，考虑到这一点，这似乎是一种完全有效的方式（根据 REST）来执行您的建议。但是，还记得之前我提到过关于 JSON 实际上没有任何应用程序级语义的内容吗？好吧，这意味着，为了让您的客户首先真正发送POST 以获取新的SpecialToken，它需要知道该资源的URL，或者至少知道如何制作这样的URL。这被认为是一种不好的做法，因为它将客户端与服务器联系在一起。让我们举例说明。

鉴于以下请求：

POST /User/1/SpecialToken
Accept: application/json

如果服务器不再识别 URL /User/1/SpecialToken，它可能会返回 404 或其他适当的错误消息，并且您的客户端现在已损坏。要修复它，您需要更改负责的代码。这意味着您的客户端和服务器不能彼此独立发展，并且您已经引入了耦合。但是，如果您的客户端 HTTP 例程允许您检查标头，则修复此问题相对容易。在这种情况下，您可以引入指向您的消息的链接。让我们回到我们的第一个资源：

请求：

GET /User/1
Accept: application/json

回复：

200 OK
Content-Type: application/json
Link: </User/1/SpecialToken>; rel=token

{
   "Id": 1,
   "Email": "myemail@gmail.com",
   "SpecialToken": "12345689"
}

现在在响应中，标题中指定了一个链接。这个小小的添加意味着您的客户不再需要知道如何访问SpecialToken 资源，它只需点击链接即可。虽然这并不能解决所有的耦合问题（例如，token 不是registered link relation，）但它确实有很长的路要走。您的服务器现在可以随意更改SpecialToken URL，您的客户端无需更改即可工作。

这是 HATEOAS 的一个小例子，是 Hypermedia As The Engine Of Application State 的缩写，本质上意味着您的应用程序会发现如何做事，而不是预先知道它们。首字母缩略词部门的某个人确实因此而被解雇。为了满足您对这个主题的兴趣，有一个really cool talk by Jon Moore 显示了一个广泛使用超媒体的 API。另一个不错的超媒体介绍是writings of Steve Klabnik。这应该可以帮助您入门。

希望这会有所帮助！

Answer 4

我突然想到了另一个想法。您可以简单地将现有的特殊令牌发布到与此用户关联的 RevokedTokens 集合（假设在给定时间每个用户只允许一个特殊令牌），而不是对 RefreshToken 资源建模。

请求：

GET /User/1
Accept: application/hal+json

回应：

200 OK
Content-Type: application/hal+json

{
   _links: {
     self: { href: "/User/1" },
     "token-revocation": { href: "/User/1/RevokedTokens" }
   },
   "Id": 1,
   "Email": "myemail@gmail.com",
   "SpecialToken": "12345689"
}

遵循令牌-撤销关系并发布现有的特殊令牌将如下所示：

请求：

POST /User/1/RevokedTokens
Content-Type: text/plain

123456789

回应： 202 接受（或 204 无内容）

用户的后续 GET 将分配新的特殊令牌：

请求：

GET /User/1
Accept: application/hal+json

回应：

200 OK
Content-Type: application/hal+json

{
   _links: {
     self: { href: "/User/1" },
     "token-revocation": { href: "/User/1/RevokedTokens" }
   },
   "Id": 1,
   "Email": "myemail@gmail.com",
   "SpecialToken": "99999999"
}

这样做的优点是对可以影响其他资源的实际资源（令牌撤销列表）进行建模，而不是将服务建模为资源（即令牌刷新资源）。

Answer 5

一个单独的资源负责刷新用户资源中的令牌怎么样？

POST /UserTokenRefresher
{
    "User":"/User/1"
}

这可能会在响应中返回刷新后的用户表示（使用新令牌）。