Understanding Query Parameter Handling in REST Calls

There is a bug in query parameter handling and you may not know it.

By Robert Delwood, A Lead API Documentation Writer

There is a bug in handling query parameters that may already be causing considerable problems and many aren’t aware of it. The truth is, it’s actually an intentional behavior but it may as well be a bug. It’s common enough it even has a name: Silent Failure. This is about handling errors, or more to the point, the lack of handling errors, in query parameter syntax.

Error Handling the Right Way

Before getting to that, it’s important to understand how errors in path and request body parameters are handled. If there is a misspelling, for instance:

• In a request body parameter, such as token-type or token_tipe for token_type, the call returns an error, likely a 400 Bad Request.
• In path parameter, such as the resource ID of Bobb_Smith does not exist in GET {{baseURL}}/v1/users/Bobb_Smith, a resource not found should be returned. The employee Bobb Smith doesn’t exist when Bob Smith was expected.
• This isn’t a path parameter but included for completeness, but should the path itself have misspelling, such as https://www.gogle.com, would return some sort of error such as 404.

These errors are not only expected but also we depend on them. Clients need to know when they’ve made a mistake specifying something.

Error Handling the Wrong Way

This behavior isn’t always the same for query parameters. What I’m calling a bug is if there is an incorrect or a misspelled query parameter. In other words, the included parameter doesn’t exactly match its specifications. The server may not return an error. Instead, it ignores all wrong parameters and continues the call using the valid parameters only. For instance, of the endpoint

GET {{baseURL}}/v1/users/bob_smith?departtment=ACCOUNTING.

Notice that departtment is misspelled. What we think should be an error, isn’t. Instead, the call is successful and returns a list of Bob Smiths. The problem is it might also include some from departments other than accounting.

This is concerning. The user has no indication the call is anything other than what they expected. Hence, silent failure. They get a 200 OK result and a valid list. The application and the user continues as if nothing is wrong. Yet, the client is processing bad, inaccurate, or undesired results. Imagine the problems this could cause, especially with medical, legal, or financial applications.

This condition is caused by one of two cases:

• The parameter is misspelled. For instance, of the previous endpoint:

GET {{baseURL}}/v1/users/bob_smith?departtment=ACCOUNTING

departtment is misspelled.

• An enum value is misspelled. If the valid value is defined as an enum or constant, such as ACCOUNTING, then misspelling it, perhaps as ACOUNTING or including value not defined as an enum, such as PAYABLES, or even XXXX. Notice that this is not the same as providing an incorrect value for items that are not enums. For instance, if the department parameter accepted any value, the application would be responsible for checking that value and possibly returning an error. For example, the application’s internal logic would have to check that PAYABLES is or isn’t valid. In that case, because there is no schema to check against, it’s not the server’s responsibility to check value legitimacy.

For these two conditions, it’s the server that should be checking the validity of the statement. If either one of those are wrong, the request shouldn’t make it to the application itself. The server rejects it. This will be important in a moment.

How This Happens

Getting to this point isn’t unusual. Clients clearly think they’re making the call correctly, or else they would fix the endpoint themselves. Some misspellings are difficult to catch. The enum USER_RETREIVE may not be noticed from USER_RETRIEVE, especially if picking it from a list. Misspellings happen and they’re not always caught before making it to the contract. As an aside, that’s why it’s important writers routinely check development’s changes. This applies, too, to our testing calls in Postman, where manually entering endpoints and values are more pervasive.

The reason this isn’t caught is simple: We’re not expecting it.

For our testing, the call is made and we get results. We may even spot check some of them. But generally, results aren’t examined that closely. For instance, how often do you so carefully examine a returned list of 50 or 100 items? You check may check that the objects are complete but not that the list conforms to the search criteria.

The reason this happens is because of an intentional behavior on the server. This behavior is called Lenient Handling or Strict Handling.

Lenient handling is the behavior discussed here. Invalid query parameters are ignored, the call only processes the valid parameters, and no error or warning of any type is returned. That’s why I call it a bug. It’s hard to believe that legitimate errors are not flagged.

Strict handling is just the opposite. Invalid query parameters are flagged as errors. These are typically a 400 Bad Request, the same as incorrect request body parameters. This is the type of handling you want.

Testing For Silent Failure

You can test for this condition. Make a call using an incorrect or even non-existent query parameter. For example, calls like:

GET {{baseURL}}/v1/users/bob_smith?departtment=accounting

GET {{baseURL}}/v1/users/bob_smith?XXXX

If the call succeeds, the server is configured to lenient handling. Unfortunately, there is not much you can do about it. One option is to include a header:

Earlier, I said “this behavior isn’t always the same for query parameters.” It’s not always the same because it’s a server setting, something that writers typically can’t control. After modifying the header, make the call again. If this doesn’t work, the server doesn’t support this option. The most you can do then is contact the server team and see if they can change this setting for you. Frankly, it’s always a good idea and there are few legitimate reasons the server team should refuse the request. It’s an obscure setting and it’s possible the server team themself doesn’t know about it.

Conclusion

You need to be aware of this case. Test your servers for this handling. Periodically check the results of calls to make sure what is returned is expected from the query parameters.