Extend description of timeout parameter

[SlowMo24]

The description in api.ohsome.org

timeout – custom timeout to limit the processing time in seconds; default: empty

is misleading. One the one hand a server side max-timeout applies (that might be documented at /metadata ) on the other the default is not 'empty' but 'some number'.

[FabiKo117]

I think the first sentence describes the usage of this parameter pretty good. The issue with the timeout is that, as far as I know, it can vary e.g. depending on the used network. In the current implementation, the timeout is set via a startup parameter (and I think it's set to 7 minutes, am I right @joker234 ?), so it can also vary. Therefore I would not write a fixed number in here in the parameter description, but your suggestion to retrieve this info through /metadata is a good one 👍 .

[SlowMo24]

currently, if I set a too large timeout I get the restriction as response (600 seconds). So communicating to the user that she is not free to choose any timeout but limited to server setting might be a good idea.

[FabiKo117]

Ok, then it's 10 minutes :D
But explain to me why someone would set an even higher timeout? That does not make sense to me.

I'd suggest the following description then:

timeout - custom timeout to limit the processing time in seconds; default: dependent on server settings, retrieveable through a /metadata request

[joker234]

Correct, 10 minutes is set, but you cannot expect that you get appropriate responses waiting 10 minutes. Some network components (outside of our scope) may restrict HTTP requests to a smaller timeout.

[SlowMo24]

@FabiKo117 the timeout is just to prevent overusage of our 'cluster', right? a longer timeout would mean one could run more complex queries (e.g. count relations in Kurpfalz, not possible with current timeout)

[FabiKo117]

The short answer is "yes". But as @joker234 already stated, depending on the network, an HTTP connection might not be open for too long regardless on what we define internally as the timeout, or what the user defines here, if it goes in the duration of several minutes.

We've added this parameter so that the user can specify an upper boundary for the processing time of the request. So if he/she reaches the custom timeout, there are two options: increase the limit, or check and inform yourself on why it takes so long (maybe too coarse filtering, API currently busy, etc.).