REST API返回非完整资源是否合规？对应端点URI应如何设计？

一、REST规范合规性判断 #

这种返回裁剪后资源的操作完全符合REST规范。
REST规范从未强制要求接口必须返回资源的全量完整表示，资源的「部分表示/投影（Projection）」是被明确允许的设计方式。你当前的需求是保留完整的offer主体字段、仅过滤掉不符合状态要求的子资源（offer item），属于典型的部分表示适用场景，只要接口的返回结构和语义明确告知调用方当前是过滤后的结果，就不存在合规问题。
小提示：可以在返回的offer结构中额外添加filtered_item_status、original_item_total这类辅助字段，避免调用方误将过滤后的item列表当做offer下的全量item。

二、示例Endpoint URI设计 #

有两种业界通用的设计方案，可根据业务场景选择：

方案1：查询参数实现（推荐，灵活性更高） #

适合后续可能需要扩展支持过滤其他offer item状态的场景，符合查询参数用于资源筛选的通用惯例：

• 获取指定用户下所有仅包含Invalid状态item的offer列表：
  GET /users/{userId}/offers?item_status=invalid
• 获取指定用户的单个offer的仅含Invalid状态item的表示：
  GET /users/{userId}/offers/{offerId}?item_status=invalid

方案2：路径视图实现 #

适合该过滤场景是业务上固定的核心高频场景，作为独立的资源视图对外提供：

• 获取指定用户下所有仅包含Invalid状态item的offer列表：
  GET /users/{userId}/offers/invalid-item-views
• 获取指定用户的单个offer的仅含Invalid状态item的表示：
  GET /users/{userId}/offers/{offerId}/invalid-item-view

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