REST API参数类型抉择咨询：查询参数还是请求头？

问题背景 #

现有GET接口 GET /device/{device_name} 用于返回设备基础详情，响应示例如下：

{
  "device_type": "ABC",
  "device_name": "XYZ",
  ...
}

需要在不破坏原有接口契约的前提下，新增返回设备实时状态的功能。最初纠结用请求头参数还是查询参数触发状态返回，最终确定采用查询参数方案，接口形式为 GET /device/{device_name}?status=true。

参数选择分析 #

选择查询参数而非请求头的核心原因：

• 查询参数的语义更贴合「按需扩展资源返回属性」的场景，其他开发者看到这个参数能立刻明白是要获取额外的设备状态信息，可读性更强
• 请求头一般用来传递接口调用的元数据（比如认证token、Accept类型），而非控制资源返回的内容范围，用在这里会违背REST接口的常规设计习惯，增加理解成本
• 可选查询参数完全兼容原有契约：调用方不携带status参数时，接口返回原有结构，不会影响旧业务逻辑

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