TLDR: Should TIMEOUT be a public property on my static class, or a parameter to every function?
Background:
I am releasing a c# client-api library that facilitates communicating with our REST api.
The client-api consists of an object model and one large static class with a bunch of request extension methods for various types. 10 or so .Get() variations, a few .Post(), .Put(), etc.
This static class full of extension methods is preconfigured with our server URL, and some other static configuration constants related to the connection. Because all the functionality is exposed via extension methods, there's no need to create an instance of this class. Any configuration is done via static properties and affects all requests made by the application.
Problem:
Right now, all requests use a default timeout of 3 seconds (which seems generous to us, as our API is meant to be very responsive.) Some users with a bad connection though might want to wait longer for a response.
Our quick-fix solution is to expose the DEFAULT_TIMEOUT at a public static property on the class which can be set once on initialization, but is the proper thing to do to add a new optional parameter to every single one of our dozens of methods?
.Get(int timeout = DEFAULT_TIMEOUT) { ... }
.Get(..., int timeout = DEFAULT_TIMEOUT) { ... }
.Get(..., ..., int timeout = DEFAULT_TIMEOUT) { ... }
.Get(..., ..., ..., int timeout = DEFAULT_TIMEOUT) { ... }
...
.Post(..., int timeout = DEFAULT_TIMEOUT) { ... }
.Put(..., int timeout = DEFAULT_TIMEOUT) { ... }
.Save(..., int timeout = DEFAULT_TIMEOUT) { ... }
...
On the one hand, we want to be flexible to whatever the consumer of our client-api library might need, but on the other hand, I won't want to get in the habit of polluting every method with every optional parameter that might impact a request (server url, authorization tokens, etc.)
What I don't want, is for the user to feel the need to do this:
ClientAPI.DEFAULT_TIMEOUT = 5000;
Thing found = new Thing(){ id = "19473" }.Get();
found.count += 1;
ClientAPI.DEFAULT_TIMEOUT = 20000;
found.Put();
ClientAPI.DEFAULT_TIMEOUT = 8000;
List<Widgets> widgets = found.GetSubresource("widgets");
...etc
Is it reasonable to assume users won't be micromanaging timeouts for individual requests like that?
Best Answer
Well it really depends on the services being provided. Some operations might be very slow and he client might be able to anticipate that (for example, requesting all transactions on some account for the last 5 years) and the user is willing to wait. Other operations might not be so slow, or the user might prefer to fail/abort/skip them if they are too slow. I would think it's better to give them the option: maybe set a "global" default when they first create the client object, and allow them to override with an optional parameter, as in your example.