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

Question

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

例子:

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

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

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

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

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

请求:

GET /User/1

响应:

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

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

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

一个想法是:

请求:

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

服务器会看到这个请求并知道它需要刷新 token 。后端将使用特定算法更新 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，但他们无法控制该值是什么，它严格来说是一个只读属性。

Answer 1

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

能够更新 token 有哪些要求？什么是 token ？可以从 User 中的其他值计算 token 吗？这可能只是一个示例，但上下文将决定您最终如何构建系统。

除非有禁止它的要求，否则我可能会通过使用 PUT“接触”资源表示来实现 token 生成场景。据推测，客户端无法更新 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 之类的模糊内容中)。

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