REST API合规性咨询：PUT创建嵌套资源及设计合理性探讨

先明确下咱们要分析的API背景：这是一个用于管理UserStore及其下属User资源的API，核心接口定义如下：

• PUT /userStores/store1：创建ID为store1的空UserStore，若已存在则不执行任何操作。
• PUT /userStores/store1 -content { "userName":"John", "more":"details" }：在ID为store1的UserStore中创建User；若该UserStore不存在则先创建，若UserStore和User均已存在则更新User详情。
• GET /userStores/store1：列出ID为store1的UserStore中的所有User。
• GET /userStores/store1/John：获取ID为store1的UserStore中名为John的User的资源表述。

接下来逐个解答提出的三个问题：

a) 该API是否符合REST原则？ #

整体来看，这个API有REST的雏形，但存在多处违反REST核心约束的问题：

• 资源标识混淆：REST要求每个资源对应唯一的URI，但这里/userStores/store1既代表UserStore资源本身，又被用来创建/更新下属的User资源，同一个URI对应两种完全不同的资源类型，违背了"URI定位唯一资源"的核心要求。
• PUT方法语义偏离：REST中PUT的标准语义是替换目标资源的全部内容，但当前设计中，带请求体的PUT /userStores/store1操作的是子资源User，而非替换UserStore自身的属性，这完全不符合PUT的规范用法。正确的做法应该是用PUT /userStores/store1/users/John来创建/更新指定User，PUT /userStores/store1仅用于更新UserStore自身的配置（比如名称、描述这类属性）。
• 资源层级表达模糊：REST依赖URI清晰表达资源层级，而这里却通过请求体内容来区分操作的资源类型，让客户端无法通过URI直接判断要操作的对象，不符合REST的设计理念。

b) 根据请求内容决定创建UserStore还是User，此设计是否合理？ #

这种设计非常不合理，主要问题集中在这几点：

• 违反统一接口约束：REST的核心约束之一是"统一接口"，要求HTTP方法的语义固定，同一个URI+方法的组合，执行的操作逻辑应该是确定的，不能根据请求体内容变化。客户端不应该需要解析请求体才能知道服务器会做什么。
• 提升客户端复杂度：客户端需要额外判断请求体是否包含userName等字段来确定操作目标，增加了逻辑负担，也容易因为字段判断错误引发bug。
• 阻碍中间件正常工作：代理、缓存等中间件通常依赖URI和HTTP方法来做策略判断，这种基于请求体的动态逻辑会让缓存失效，也难以进行流量监控、路由等运维操作。

c) 单次PUT同时创建不存在的UserStore和User是否可行？ #

从技术实现上来说是可行的——服务器端可以先检查UserStore是否存在，不存在就先创建，再创建对应的User，代码层面完全能做到。但从REST设计规范和系统可维护性来看，非常不推荐这么做：

• 违背单一职责原则：一个请求应该只完成一个资源的创建/更新操作，同时处理两个层级的资源会让接口逻辑变得复杂，增加出错概率，后续排查问题也会更麻烦。
• 不符合资源定位原则：REST强调每个资源有独立的URI，创建子资源应该通过子资源的专属URI（比如PUT /userStores/store1/users/John）来操作，而不是复用父资源的URI。
• 状态反馈不清晰：如果创建UserStore成功但创建User失败，服务器很难用一个HTTP状态码准确反馈这种部分成功的情况，客户端处理这类异常会非常棘手。

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