在设计RESTful API时，一个常见的难题是如何在不破坏现有API契约的前提下，添加新的可选参数。一个典型的场景是：现有的API返回设备详情，现在需要增加返回设备状态的功能，并且这个状态是可选的。那么，应该使用查询参数还是请求头来传递这个可选参数呢？
方案选择：查询参数
通常情况下，推荐使用查询参数来传递这种可选的、用于控制返回结果的参数。查询参数的主要作用是过滤或修改响应。
例如，对于获取设备详情的API /device/{device_name}，如果需要获取设备状态，可以使用以下形式的请求：
GET /device/{device_name}?status=true这种方式的优点是：
- 语义明确：查询参数明确表示客户端希望对返回结果进行某种形式的过滤或修改。
- 易于理解：查询参数易于理解和调试，可以直接在URL中看到。
- 符合RESTful原则：符合RESTful API的设计原则，利用HTTP动词和URI来表达资源的操作。
替代方案
除了使用查询参数外，还有其他几种方案可以考虑：
-
直接在响应中添加状态字段
如果客户端能够容忍响应结构的改变，最简单的方法是在现有的JSON响应中直接添加status字段：
{ "device_type": "ABC", "device_name": "XYZ", "status": "operational" }但这种方案可能会破坏一些对响应结构有严格依赖的客户端。
-
新增API端点
可以创建新的API端点来返回包含状态信息的设备详情：
GET /device/{device_name}/status GET /device/{device_name}/with-status GET /device/{device_name}?with-status=true这种方式的优点是保持了现有API的兼容性，但可能会增加API的数量，导致API设计不够简洁。
-
API版本控制
如果需要对API进行较大的改动，可以考虑使用API版本控制：
GET api/v1/device/{device_name} GET api/v2/device/{device_name}这种方式可以保证现有API的完全兼容性，但需要维护多个版本的API。
不推荐方案：请求头
通常不建议使用请求头来传递这种用于控制业务逻辑的参数。请求头主要用于传递HTTP协议相关的元数据，例如Content-Type、Authorization等。虽然请求头也可以传递自定义参数，但这种方式不够直观，也不符合RESTful API的设计原则。
总结
在设计REST API时，选择合适的参数传递方式至关重要。对于可选的、用于控制返回结果的参数，推荐使用查询参数。如果需要对API进行较大的改动，可以考虑使用API版本控制。避免使用请求头传递业务逻辑参数，以保持API的清晰性和可维护性。同时，在添加任何新的API功能时，都应该仔细评估对现有客户端的影响，并尽可能地保证API的兼容性。
