How should a web API handle misspelled/extra parameters?

Question

Question: For a public facing web API(send HTTP Get/Post requests, get JSON/XML data back), how should parameters be handled that are either misspelled or are extra.

It seems to me that if the incorrect parameters are ignored, an error in the caller's code may go unnoticed since they would be getting back a valid result. This may be especially true in situations where it wouldn't be obvious by looking at the results returned.

I am referring to optional parameters only. Obviously if a required parameter is misspelled, then the parameter will be considered missing and an error will be returned.

As an example, the Place Search API call has four required parameters(location,radius,sensor and key) and several optional parameters(types is one of them).

I can run these commands(with an API key) and get back valid results:

curl "https://maps.googleapis.com/maps/api/place/search/json?location=45.47554,-122.794189&radius=500&sensor=false&key=<api_key>&type=bakery"

curl "https://maps.googleapis.com/maps/api/place/search/json?location=45.47554,-122.794189&radius=500&sensor=false&key=<api_key>&types=bakery"

The first command has the "types" parameter in the singular form which is an invalid key name. The API ignores that parameter and returns all types of entities. In this case the error is obvious, but there may be times(and other API calls) where it won't be.

Answer 1

Ignoring extra parameters is standard practice. It's easy to write code like this

if (params.type) { 
  ... 
}

It's not worth the trouble to check all the passed parameters to see if any are invalid. Misspellings are the client's problem.

Answer 2

I think it depends on how the API is spec'd and who has been made responsible for these issues. If I were to design an API then I would put the ownership of making sure the correct parameters expected (and their associated values if any) were handled in the expected manner or if there was unexpected input (as required to protect the method from weird and wacky data) then the appropiate exception was thrown or error-code was returned.

I would then say that all inputs not part of the expected parameter lists are not part of the API's issue. That allows you to be specific and take ownership of a very defined specification and anyone who wants to use that are responsible for ensuring they use it properly.

You have provided a tool and a set of instructions on how to use it. Make it the responsibility of the user to use it right.

Answer 3

If it were a small effort to include a misspelling test for parameter names (how much work do you want to do, checking the names of ALL parameters against a list of most-likely misspellings?), I might do it but normally I'd recommend just ignore the extra paramters that are misspelled. Of course, it might be nice if a WebService sends back a message "No valid paramter type, did you mean types?" but only if you have the time to implement it properly, and since I don't usually expect that type of message to come back, I won't miss it if it isn't there.