考虑一个接受 GET 请求以列出项目的 RESTful API:
GET /1.0/items/
>> {"items": [{}, {}, ..., {}]} # All items returned
Run Code Online (Sandbox Code Playgroud)
现在考虑每个项目都有一个颜色字段,我可以过滤我的项目:
GET /1.0/items?color=blue
>> {"items": [{}, {}, ..., {}]} # Only blue items returned
Run Code Online (Sandbox Code Playgroud)
如果我的 API 收到无效的查询参数(不是有效查询参数上的无效值):
GET /1.0/items?notvalid=blue
Run Code Online (Sandbox Code Playgroud)
预期的行为应该是什么?我的 API 是否应该返回一个4xx响应,通知客户端请求无效,或者 API 是否应该执行项目列表,就好像没有提供过滤器参数一样?
我的 API 是否应该返回 4xx 响应,通知客户端请求无效,或者 API 是否应该执行项目列表,就好像未提供过滤器参数一样?
/1.0/items?notvalid=blue标识资源。该标识符可以解释为分层部分和查询(请参阅RFC 3986,第 3 节),但标识符是整个事物。文档存储遇到不存在的资源的 URI 时,会返回 404 错误。因此,这种行为是完全可以接受的(也可以使用更常见的 400 错误,但这并不常见)。
另一种有价值的替代方法是使用必须忽略的策略。将 URI 视为键值对的 x-www-form-urlencoded 表达式,可以随意接受查询,忽略无法识别的键,并为任何缺少的键提供默认值。
采用这种方法,该标识符将被视为已拼写/1.0/items? 这为您提供了一些针对更改的保护(客户端和服务器不需要达成确切的协议即可取得进展)。
注意:在 REST 中 - 客户端通常会使用超媒体表示来引导其完成协议;因此,客户端将通过表单或 uri 模板发现哪些参数应作为查询字符串的一部分。这实际上是相同的必须忽略的语义,但应用在不同的地方。
API 是否应该像未提供过滤器参数一样执行项目列表?
您可能希望明确标识您要返回的引用,以便客户端可以检测到差异;例如,通过将请求重定向到您要返回的名称,或者返回Content-Location标头。