5

I have a web service which allows to retrieve users: http://example.com/users. It returns a list of users.

That service accepts a number of parameters (age, gender) to select which users to retrieve. Examples:

  • http://example.com/users?age=34
  • http://example.com/users?gender=male

Should that service return an error message if the client is passing an unknown parameter? Example:

>>> GET http://example.com/users?cylinders=16 
<<< 400 Bad Request
<<< { 'message' : "Invalid parameter 'cylinders'" }

(To me it's clear that a web service should validate the parameters it receives, but the case of unknown parameters is not clear to me)

6

Technically, such checking requires an additional step. You have to list all the parameters, and compare this list with the list of allowed ones. Then, if you decide to accept an additional parameter, you have to change this list, requiring even more work. All this code has to be tested as well.

What's the benefit? The benefit is that a programmer who made a typo such as:

                             ↓↓
http://example.com/users?gendre=male

will immediately see a helpful error message, instead of receiving the list of all users and wondering why is the filter not working. That's great, and I wish all APIs were that helpful and programmer-friendly.

It's up to you to decide whether this benefit is worth the effort of writing additional code and tests.

One of the cases where you shouldn't care is when you develop the client libraries yourself. If you provide those libraries in most popular languages (Java, Python, Ruby, C++, C#, ObjectiveC, PHP), it may not be that useful to handle the case where a non-supported parameter was specified.

4
  • Actually this question can be treated as a more generic one: "how far should you go into error handling?". As you answered, it all depends on how user-friendly you want to be. I don't agree with your latest remark though. Sure it would be less important if you're developing the client libraries, but in the case of a typo, you would be glad that your programmer-friendly error handling is existing... and anyway you never know who may need a client library in which language. in the end, it's indeed always the same dicussion of ROI: is it really worth it ? – Laurent S. Aug 21 '15 at 13:52
  • 1
    I guess I'm selfish that way, but I actually care more when I'm the one who has to personally deal with bad/nonexistent error messages. – Karl Bielefeldt Aug 21 '15 at 14:37
  • @LaurentS.: if you're developing the client libraries, you will be the only one making typos in a context of specific languages. Of course, someone could start developing a client library for Ada or COBOL, but this won't happen too often. – Arseni Mourzenko Aug 21 '15 at 14:51
  • You hit the nail on the head there: Actually, the reason that got me thinking about that is that one of our clients made exactly the typo you were talking about and was wondering about the filter not working. – Silvan Mühlemann Aug 21 '15 at 20:18

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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