如何在超媒体api的更新请求中引用资源

Question

我做了一些关于RESTAPI如何工作以及如何通过超媒体链接资源的研究。关于链接资源的大多数示例都与服务器的响应有关。但我想知道当某个资源应该更新时，如何引用其他资源。

让我们以一个居住在特定地点的人的简单资源为例：

/api/persons/alice
{
"name": "Alice",
"location": {
"id": 1,
"links": {
"self": "/api/locations/1"
}
}
}

现在我想将该位置更新到另一个现有位置。但我该如何表示呢？我会：

1. 参考新位置的id

PUT /api/persons/alice
{
"name": "Alice",
"location": 2
}

2. 引用新位置的URI

PUT /api/persons/alice
{
"name": "Alice",
"location": "/api/locations/2"
}

3. 还有别的吗

Answer 1

HTTP PUT具有远程创作语义-您应该将有效负载视为文档的新表示，由一些通用的HTTP感知文档编辑器进行操作。

GET /api/persons/alice HTTP/1.1

HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "Alice",
"location": {
"id": 1,
"links": {
"self": "/api/locations/1"
}
}
}

PUT /api/persons/alice HTTP/1.1
Content-Type: application/json
{
"name": "Alice",
"location": {
"id": 2,
"links": {
"self": "/api/locations/2"
}
}
}

200 OK

这里的假设是，API的使用者熟悉这里的模式，并理解语义，哪些字段是可选的，哪些是必需的，等等

(要让它在长时间内发挥作用，就意味着要在设计好模式、选择合理的默认值等方面投入精力(。

请小心遵守PUT规范的这一部分：

源服务器应该验证PUT表示是否与服务器对目标资源的任何约束一致，这些约束不能或不会被PUT…更改。。。。当PUT表示与目标资源不一致时，源服务器应该通过转换表示或更改资源配置来使它们一致。。。

。。。

在对PUT的成功响应中，源服务器不得发送验证器标头字段(第7.2节(，如ETag或Last Modified字段，除非保存了请求的表示数据而未对主体应用任何转换。。。。

换句话说，服务器不需要；存储"；所提供的新表示。