Should a client check for valid parameters?

The main questions are: Where does the value come from and how likely is it the allowed range changes? Secondary: What's the cost and consequence of sending a wrong request?

In general a check in the client manifests the API. Maybe in a future release the API allows a higher count. If this is limited in too many places you have a harder time to adopt to this.

On the other side there are usability questions. If the value is entered by the user and you can give immediate feedback usability is a lot higher thane when you first have to send this to a sever which then has to process this. However if this is a value calculated by your app you should check your algorithms carefully as this might find more bugs.

Thirdly there can be other costs from invalid requests. For instance the API might be rate limited or charge per request. For some services even invalid requests could lead to complex calculation and wasted CPU resources. Avoiding invalid requests there can save money.

Checking the value on the client is a good idea, because if the value is recognized as incorrect on the client side you are not wasting bandwidth by making a trip to the server which would return a failed code anyway.

But even with the client implementing the validation, the server still should include its own validation of the passed data and never trust an unprocessed input.

If I was writing the REST client, I would expect an "HTTP 400 Bad Request" from the server. And if I was writing java code invoking some client-side library that ultimately places REST calls to a server, I would expect some IllegalArgument exception.

There is nothing in this question which is specifically pertinent to java, or to REST APIs, (*) or to client-side programming, or to server-side programming. The fact is, you are programming against an interface. An interface is two things:

1. An interface is an abstraction.

As an abstraction, the interface should preferably hide all implementation-specific details from the caller. With respect to parameter validation, this is a gray area, because for each parameter you have to consider whether its limits are what they are due to the nature of the interface, or due to peculiarities of the implementation. For example, if the server offers a deck of cards, then a limit of 50 would be a peculiarity of the implementation, since decks of cards normally have 52 cards, or 54 if jokers are allowed. If the limit was 52, then you could say that this is an interface for a deck of cards without jokers, and consider the limit to be part of the interface.

So, to sum up, if a limit can be included in the implementation-agnostic description of the interface, then by all means validate it. If not, skip it and let the implementation validate it. But be sure to first read the next section.

2. An interface is contract.

If you were to let the other side do as it pleases, without ever checking to see whether they are honoring their side of the contract, you are setting yourself up to be taken advantage of. Your life is going to be hard.

As a matter of fact, common decency dictates that you should check everything you can reasonably check even on your outbound calls, so as to:

• ensure that you are never violating the contract from your side, and

• know when you did something wrong without having to rely on the other side doing their job properly and validating your calls.

_{(*) Would this nasty habit of saying "API" while in fact meaning "REST API" die a nasty death? thanks!}

Checking the value and throwing an exception is an implementation of a Fail Fast system. It's value depends on the further consequences of the error. If accepting an incorrect value may lead to mysterious errors later, it's definitely easier to correct by failing immediately.

If there is an API then there should be a spec for the API. And you'd hope the spec is for a reasonable API. There's the time where you develop the client against the spec, and letter there's the time where people use the client (and the spec might change).

During development you'd want the client to fail hard so that the developers fix their code.

After development, either the spec remains unchanged, or the API is designed so that the spec can change and the client run unchanged.

Since the server has the definitive knowledge about a limit for count, for example (and it knows better than the client which is just guessing, and better than the spec, because the spec is just a spec, but the server code is the truth), I'd prefer an interface where the client can ask for whatever it wants, and gets whatever the server is willing to give it, and can figure out easily how to get anything that isn't there.

In this situation for example, the client might ask for n items. The server limit might be m items, and there might be k items actually present. The number of items returned could then be min (n, m, k), and the "accepted" number of items would be min (n, m). The server can return both numbers together with the results of the request, so any situation can be handled. (And obviously there is a "start" parameter missing, so consecutive calls can handle all the data).

Think about it: If the client requests 52 items, and as a result an exception is thrown, what would the client then do?