不删除资源仅清除resourceValues的RESTful API方案咨询

背景 #

我们目前通过POST /v1/api/resource接口创建资源R1，请求体格式如下：

{
    "resourceValues": {
         "CustomerName": "customer_name",
         "CustomerLocation" : "USA",
         ...
    },
    "ttl": "30d",
    "clientId": "id-12234"
}

创建完成后，返回的响应结构如下：

{
     "resourceId": "resource-id-1234",
     "resourceExpiry": "Some Date",
     "resourceAccessLink": "link to the resource",
     "resourceValues": { // 与用户传入内容完全一致
     }
}

现在需要设计一个符合行业标准的RESTful API，实现不删除整个资源，仅清空resourceValues字段的功能（用户无法编辑resourceValues内容，只能清空）。下面针对给出的备选方案逐一分析，并给出推荐：

备选方案分析 #

1. PATCH /v1/api/resource/，请求体为{resourceValues: {}} #

• 可行但语义不够精准：PATCH用于资源的部分更新，把resourceValues设为空对象确实能达到清空效果。但如果后续业务允许编辑resourceValues的具体内容，这个接口会同时承载"清空"和"部分更新"两种场景，容易造成混淆。不过当前需求下用户无法编辑，所以暂时能用，但扩展性一般。

2. PUT /v1/api/resource//resourceValues #

• 语义勉强：PUT用于替换整个子资源，传入空对象替换原有resourceValues虽能实现功能，但PUT通常要求传入完整的子资源表示，用它做清空操作，开发者初次接触时可能会困惑，不够直观。

3. POST /v1/api/resource//clearResourceValues #

• 偏离REST原则：这是RPC风格的接口，用POST触发一个"清空动作"而非操作资源本身。REST强调资源导向，这种命名方式会让API结构偏离REST设计规范，不利于长期维护和扩展。

4. POST /v1/api/resource//resourceValues/.clear #

• 问题同方案3：本质还是触发动作，只是路径更贴近子资源，但.clear这种命名不规范，同样不符合REST的资源导向理念。

5. DELETE /v1/api/resource//resourceValues #

• 最符合REST标准：把resourceValues看作资源R1的一个子资源，DELETE操作的语义就是移除这个子资源，对应业务上的"清空"需求，完全匹配REST的设计原则。接口语义清晰，开发者一看就知道用途，而且后续如果要对resourceValues做其他子资源级操作，也能保持API风格一致。

推荐方案 #

优先选择方案5：DELETE /v1/api/resource//resourceValues，理由如下：

• 完美贴合REST的资源导向思想，用标准HTTP方法表达操作意图，无需额外文档解释。
• 接口命名直观，降低开发者的理解成本。
• 扩展性强，后续对子资源的操作可以沿用相同的资源路径风格。

如果团队对"DELETE子资源等同于清空"的语义存在顾虑，方案1（PATCH）可以作为次选，它在部分更新的语义下实现清空功能，也符合REST规范，只是语义精准度稍逊一筹。

内容的提问来源于stack exchange，提问作者LifeIsButifool