2017-04-03 83 views
3

考虑接受GET请求列表项的一个RESTful API:当提供无效查询参数时,REST API是否应返回4xx响应?

GET /1.0/items/ 
>> {"items": [{}, {}, ..., {}]} # All items returned 

现在考虑每个项目都有一个色域,而且我可以过滤我的项目:

GET /1.0/items?color=blue 
>> {"items": [{}, {}, ..., {}]} # Only blue items returned 

如果我的API收到无效的查询参数(上一个有效的查询参数不无效值):

GET /1.0/items?notvalid=blue 

预期的行为应该是什么?我的API是否应该返回一个4xx响应,通知客户端请求无效,或者API是否应该执行项目列表,就好像没有提供过滤器参数一样?

回答

2

我的API是否应该返回4xx响应,通知客户端请求无效,或者API是否应该执行项目列表,就好像没有提供过滤器参数一样?

/1.0/items?notvalid=blue标识资源。该标识符可以解释为分层部分和查询(请参阅RFC 3986, section 3),但标识符是整个事物。面对不存在的资源的URI的文档存储将响应404错误。所以这种行为是完全可以接受的(也可能使用更一般的400错误,但这并不常见)。

另一种方法,它的优点是使用must ignore策略。将URI作为键值对的x-www-form-urlencoded表达式处理,可以查询,忽略未识别的键,并为缺失的任何键提供默认值。

采取这种方法时,该标识符将被视为拼写为/1.0/items?这可以为您提供一些防止更改的保护(客户端和服务器无需完全一致地取得进展)。

注意:在REST中 - 客户端通常会使用超媒体表示来引导它通过协议;因此客户端会通过表单或uri模板发现哪些参数是查询字符串的一部分。这实际上是一样必须忽略的语义,但是应用在不同的地方。

API应该执行项目列表,就像没有提供过滤器参数一样?

您可能希望明确标识您要返回的参考,以便客户端可以检测出差异;例如将请求重定向到要返回的标识,或者返回Content-Location标头。

1

根据JSON API文档:

在大多数情况下,JSON API要求服务器在遇到一个JSON API定义的查询参数值无效返回一个错误。但是,对于特定于API的查询参数(即那些未由JSON API定义的参数),,服务器可能会选择忽略无效参数并使请求成功,而不是以错误进行响应。

这是我通常在API上看到的行为。