RESTful API - Correct behaviour when spurious/not requested parameters are passed in the request

Question

We are developing a RESTful api that accepts query parameters in the request in the form of JSON encoded data.

We were wondering what is the correct behaviour when non requested/not expected parameters are passed along with the required ones.

For example, we may require that a PUT request on a given endpoint have to provide exactly two values respectively for the keys name and surname:

{
    "name": "Jeff",
    "surname": "Atwood"
}

What if a spurious key is passed too, like color in the example below?

{
    "name": "Jeff",
    "surname": "Atwood",

    "color": "red"
}

The value for color is not expected, neither documented.

Should we ignore it or reject the request with a BAD_REQUEST 400 status error?

We can assert that the request is bad because it doesn't conform to the documentation. And probably the API user should be warned about it (She passed the value, she'll expects something for that.)

But we can assert too that the request can be accepted because, as the required parameters are all provided, it can be fulfilled.

Answer 1

Having used RESTful APIs from numerous vendors over the years, let me give you a "users" perspective.

A lot of times documentation is simply bad or out of date. Maybe a parameter name changed, maybe you enforce exact casing on the property names, maybe you have used the wrong font in your documentation and have an I which looks exactly like an l - yes, those are different letters.

Do not ignore it. Instead, send an error message back stating the property name with an easy to understand message. For example "Unknown property name: color".

This one little thing will go a long ways towards limiting support requests around consumption of your API.

If you simply ignore the parameters then a dev might think that valid values are being passed in while cussing your API because obviously the API is not working right.

If you throw a generic error message then you'll have dev's pulling their hair out trying to figure out what's going on and flooding your forum, this site or your phone will calls asking why your servers don't work. (I recently went through this problem with a vendor that just didn't understand that a 404 message was not a valid response to an incorrect parameter and that the documentation should reflect the actual parameter names used...)

Now, by the same token I would expect you to also give a good error message when a required parameter is missing. For example "Required property: Name is missing".

---

Essentially you want to be as helpful as possible so the consumers of your API can be as self sufficient as possible. As you can tell I wholeheartedly disagree with a "gracious" vs "stern" breakdown. The more "gracious" you are, the more likely the consumers of your API are going to run into issues where they think they are doing the right thing but are getting unexpected behaviors out of your API. You can't think of all possible ways people are going to screw up so enforcing a strict adherence with relevant error messages will help out tremendously.