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.

http://stackoverflow.com/questions/15947074/extra-query-parameters-in-the-rest-api-url.. check my answer too — Vineet Singla, Dec 19 '13 at 11:06
my question is actually a duplicate of yours. I didn't find it when I searched before posting... However interesting new answers came out. I like the stern vs graciuos paradigm suggested by xwoker. — Paolo, Dec 19 '13 at 14:14

NotMe · Accepted Answer · 2013-12-19T16:56:58.883

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.

I totally agree regarding "give them any hints that help them understand the API. So if they use unknown properties please **inform** them that this is the case. What we don't agree on whether this is an error case that hinders the processing of an otherwise valid message *in every situation*. — xwoker, Dec 20 '13 at 13:13
This is what I want to hear but for some reason REST API from big Internet companies such as Google, Twitter and Facebook simply ignore unknown properties :( — LostInComputer, Jan 31 '17 at 08:53
@LostInComputer: IMHO, ignoring unknown properties can be a decent way to handle things as long as 1. nothing is case sensitive - that's the easiest way to screw up. 2. API is well documented and 3. you give rock solid error messages about the parameters that are expected. — NotMe, Jan 31 '17 at 19:11
I don't really see the argument for why it's better to throw an error when you receive an extra parameter that you did not expect. Obviously if you require a `"name"` parameter and you don't get one, return a 400. But if you get everything you need, and in the proper format, you are perfectly capable of carrying on. What is the need to reject a request that contains all necessary information just because it _also_ contains unnecessary information? — ewok, May 22 '19 at 19:33
@ewok: imagine that your case sensitive API has an optional parameter for "Description". Now imagine someone passes a value for "description". Your API ignores this value and doesn't say anything about it. Meanwhile the developers start pulling their hair out trying to understand why the "description" they gave you isn't being saved. Probably the best way to handle this would be to send back a warning message that "description" is not a valid parameter while still processing the rest of the transaction. This would inform the devs while allowing them to decide to ignore it if they choose — NotMe, Feb 21 '20 at 01:48

score 22 · Answer 2 · edited May 23 '17 at 12:10

If you do an API design you can follow two path: "stern" or "gracious".

Stern means: If you do anything I didn't expect I will be mad at you.
Gracious means: If I know what you want and can fulfil it I will do it.

REST allows for a wonderful gracious API design and I would try to follow this path as long as possible and expect the same of my clients. If my API evolves I might have to add additional parameters in my responses that are only relevant for specific clients. If my clients are gracious to me they will be able to handle this. Having said that I want to add that there is a place for stern API design. If you are designing in an sensitive domain (e.g. cash transactions) and you don't want to leave room for any misunderstanding between the client and server. Imagine the following POST request (valid for your /account/{no}/transaction/ API):

{ amount: "-100", currency : "USD" }

What would you do with the following (invalid API request)?

{ amount: "100", currency : "USD", type : "withdrawal" }

If you just ignore the "type" attribute, you will deposit 100 USD instead of withdrawing them. In such a domain I would follow a stern approach and show no grace whatsoever.

Be gracious if you can, be stern if you must.

Update:

I totally agree with @Chris Lively's answer that the user should be informed. I disagree that it should always be an error case even the message is non-ambiguous for the referenced resource. Doing it otherwise will hinder reuse of resource representations and require repackaging of semantically identical information.

In my opinion, once a release version of a REST API is fully developed, it should be locked as it is, except for bug fixes and that also depends on when they are caught. All new features (including new body and path parameters), should be part of a new version. Years of consuming from APIs thought me that. If a dynamic/gracious API is needed, then something like GraphQL may fit better. — Peter Majko, Sep 09 '21 at 12:10

score 1 · Answer 3 · edited May 23 '17 at 12:18

1

It depends on your documentation.. how strict you want to be ..
But commonly speaking, Just ignore it. Most other servers also ignore request parameters it didn't understand.

Example taken from my previous post

Extra Query parameters in the REST API Url

"""Google ignore my two extra parameters here https://www.google.com/#q=search+for+something&invalid=param&more=stuff"""

edited May 23 '17 at 12:18

Community

1
1

answered Dec 19 '13 at 11:05

Vineet Singla

1,609
2
20
34

score 0 · Answer 4 · answered May 23 '18 at 03:21

Imagine I have the following JSON schema:

{
   "frequency": "YEARLY",
   "date": 23,
   "month": "MAY",
}

The frequency attribute accepts "WEEKLY", "MONTHLY" and "YEARLY" value. The expected payload for "WEEKLY" frequency value is:

{
   "frequency": "WEEKLY",
   "day": "MONDAY",
}

And the expected payload for "MONTHLY" frequency value is:

{
   "frequency": "MONTHLY",
   "date": 23,
}

Give the above JSON schema, typically I will have need a POJO containing frequency, day, date, and month fields for deserialization.

If the received payload is:

{
   "frequency": "MONTHLY",
   "day": "MONDAY",
   "date": 23,
   "year": 2018
}

I will throw an error on "day" attribute because I will never know the intention of the sender:

frequency: "WEEKLY" and day: "MONDAY" (incorrect frequency value entered), or
frequency: "MONTHLY" and date: 23

For the "year" attribute, I don't really have choice. Even if I wish to throw an error for that attribute, I may not be able to. It's ignored by the JSON serialization/deserialization library as my POJO has no such attribute. And this is the behavior of GSON and it makes sense given the design decision.

Navigating the Json tree or the target Type Tree while deserializing

When you are deserializing a Json string into an object of desired type, you can either navigate the tree of the input, or the type tree of the desired type. Gson uses the latter approach of navigating the type of the target object. This keeps you in tight control of instantiating only the type of objects that you are expecting (essentially validating the input against the expected "schema"). By doing this, you also ignore any extra fields that the Json input has but were not expected.

As part of Gson, we wrote a general purpose ObjectNavigator that can take any object and navigate through its fields calling a visitor of your choice.

Extracted from GSON Design Document

score -1 · Answer 5 · answered Dec 11 '13 at 18:19

-1

Just ignore them.

Do not give the user any chance to reverse engineer your RESTful API through your error messages.

Give the developers the neatest, clearest, most comprehensive documentation and parse only parameters your API need and support.

answered Dec 11 '13 at 18:19

Simone Conti

306
4
9

4

I think this is a bad advice. A list of admitted parameters is a very useful hint for your api consumers in my opinion. If you ignore an unknown parameter, you are not telling them why the api doesn't work as they thought. – fat May 24 '15 at 10:55
5

How would anyone "reverse engineer" your API based on sending them what amounts to a snippet of your docs back when they make a mistake? – AJB Sep 19 '16 at 04:02

score -1 · Answer 6 · edited May 27 '17 at 21:46

-1

I will suggest that you ignore the extra parameters. Reusing API is a game changer in the integration world. What if the same API can be used by other integration but with slightly extra parameters?

Application A expecting:

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

Application B expecting:

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

Simple get application application A to ignore "color" will do the job rather to have 2 different API to handle that.

edited May 27 '17 at 21:46

Bilesh Ganguly

3,792
3
36
58

answered May 27 '17 at 17:04

Foo

9

1

Seems that you are repeating an existing answer to an older question. Please read this [how-to-answer](http://stackoverflow.com/help/how-to-answer).for providing a quality answer. – thewaywewere May 27 '17 at 17:33

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

6 Answers6

Linked