当提供无效的查询参数时，REST API是否应返回4xx响应？

Question

Consider a RESTful API that accepts GET requests to list items:

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

Now consider that each item has a color field, and I can filter my items:

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

If my API receives an invalid query parameter (not an invalid value on a valid query parameter):

GET /1.0/items?notvalid=blue

What should the expected behavior be? Should my API return a 4xx response informing the client that the request was invalid, or should the API perform the listing of the items as if no filter parameter was supplied?

Answer 1

Should my API return a 4xx response informing the client that the request was invalid, or should the API perform the listing of the items as if no filter parameter was supplied?

/1.0/items?notvalid=blue identifies a resource. This identifier can be interpreted as a hierarchical part and a query (see RFC 3986, section 3 ), but the identifier is the whole thing. A document store, faced with a URI for a resource that doesn't exist, would respond with a 404 error. So that behavior is perfectly acceptable (one might also use the more general 400 error, but that's not common).

An alternative approach, that has merit, is use a must ignore policy. Treating the URI as a x-www-form-urlencoded expression of key-value pairs, one can liberally accept the query, ignoring the keys that are not recognized, and providing default values for any keys that are missing.

Taking that approach, this identifier would be treated as though it had been spelled /1.0/items? This gives you some protection against change (clients and servers don't need to have exact agreement to make progress).

Note: in REST - the client would normally be consuming hypermedia representations that guide it through the protocol; thus the client would discover, via forms or uri templates, which parameters were expected as part of the query string. This is really just the same must-ignore semantic, but applied in a different place.

should the API perform the listing of the items as if no filter parameter was supplied?

You might want to explicitly identify the reference you are returning, so that the client can detect the discrepancy; for instance by redirecting the request to the identify that you are going to return, or by returning a Content-Location header.

Answer 2

According to JSON API documentation:

In most cases, JSON API requires the server to return an error when it encounters an invalid value for a JSON API–defined query parameter. However, for API-specific query parameters (ie those not defined by JSON API), a server may choose to ignore an invalid parameter and have the request succeed, rather than respond with an error .

This is the behavior that I usually see on APIs.