20

I'm designing a RESTful API and faced with the title problem, restated for clarity:

Should I fail fast if a client sends an unrecognized parameter? For example,

http://example.com/api/foo?bar=true&paula=bean

In the above, bar is a valid parameter but paula is not specified by the API. Should I

  • Warn the client of the error
  • Fail fast
  • Ignore it

If I warn the client, I can only issue a warning for the first parameter, since they could be sending a near-infinite number of them, and the server presumably has better things to do. Similarly, when failing, it would only specify the first invalid param as the problem.

I prefer failure over issuing a warning to force the programmer to take action, as they might otherwise ignore the problem and keep wasting resources, or end up cargo-culting themselves inadvertently. Doing nothing is even worse in that respect.

Do my arguments make sense? Is there an accepted practice on such things?

4
  • Based on a small test, all sites that I tested simply ignore the unknown parameters that I supplied them. Commented Mar 1, 2016 at 11:54
  • @BartvanIngenSchenau Same here. It's fine for web pages but I don't think it's ok for an actual API
    – rath
    Commented Mar 1, 2016 at 12:04
  • 4
    A concern is forward compatibility. If unknown arguments are ignored it is possible to use them in future versions in such a way that clients can program to the new API and still get reasonable behavior on old servers.
    – walpen
    Commented Mar 1, 2016 at 12:14
  • @walpen That's an interesting point. Using versioned URLs api/v1 etc. would take care of that, but it still doesn't allow for incremental updates. +1
    – rath
    Commented Mar 1, 2016 at 12:37

3 Answers 3

15

In my opinion, you should return an Invalid Request status, so that the client knows that what it's trying to do isn't valid. My opinion on this is influenced by the concept that RESTful APIs are discoverable. If you're providing sufficient information up front, then the client never tries to make an invalid request to begin with. If it does, then there's something wrong in the client code and failing fast will alert the second to this bug. Of course, that's a very purist approach and may not be recommended if your API isn't discoverable.

A more pragmatic approach may be to ignore the invalid params, but either way you go, be sure to document the behavior well.

5
  • 2
    As an extension: if a client send some unknown/readonly/deprecated parameters, that means, that the client expects some behavior which will not be fulfilled. And therefore it is dangerous to perform any action. So I agree, strictly Bad Request Commented Jun 2, 2016 at 17:38
  • 2
    Thanks @StepanStepanov, but there is the "Be permissive in what you accept, explicit about what you send out" philosophy underlying much of the web's architecture. With that in mind, I could easily write an answer in direct opposition to the one I already wrote.
    – RubberDuck
    Commented Jun 2, 2016 at 18:55
  • 6
    I've googled this )) And the page about Postel's law says also "code that receives input should accept non-conformant input as long as the meaning is clear". I think, if client send us some unknown parameter, its meaning cannot be clear. If client sends us a deprecated parameter it is clear, it will not work as before and as client expects. If client send us a read-only parameter it is clear, it will be not written as client wants. Commented Jun 3, 2016 at 8:51
  • Postel disagrees. en.wikipedia.org/wiki/Robustness_principle
    – user949300
    Commented May 24, 2020 at 18:04
  • 2
    I disagree with this. One example of an arbitrarily added parameter that should not be blocked is a cache-buster. Your proposed solution would effectively make it impossible for frontends to avoid browser or network caching issues (which are beyond your api's control) - or you're signing yourself up for your api having to explicitly allow for this by defining a specific query parameter that you allow which consumers then need to be informed about.
    – Flater
    Commented May 25, 2020 at 9:46
2

I'd just warn them but still allow unknown query parameters.

Remember, sometimes it's going to be you who will deprecate query parameters. I don't think your clients would appreciate it if you decide to change how an endpoint works, breaking their code in the process. Accepting useless input is something you have to tolerate as a trade off for forward compatibility.

Versioning your API is the correct way of deprecating query parameters, because a version change is the moment when your clients will go through your documentation again and rebuild their request payloads.

I think it'd be unmanageable if every incremental update risks breaking your API.

1
  • 2
    If possible, the reply could document exactly which parameters were used. So, if caller requested ?bar=true&paula=bean and paula is invalid, it could return (here I;m using JSON) something like requestParameters: { bar: true }
    – user949300
    Commented May 24, 2020 at 18:02
1

If you do public API (or api that will be used by other team), I would recommend return error as @RubberDuck suggested.

If your api will be consumed only inside your team (or only by yourself), it maybe easier to ignore extra fields (e.g. requires less code and easier to do).

Not the answer you're looking for? Browse other questions tagged or ask your own question.