Mandatory query parameters or defaults for optional parameters

[gerritsj]

Not all query parameters are indicated as mandatory or contain a default value. For example, in the coverages/{coverageId}/data end point all parameter seem to be optional without default values. The startTime parameter, for example, should be either mandatory or have a sensible default.

[GeriWolters]

I see your issues, but I also see reasons why optional parameters without defaults has it's uses.

The problem is with sensible defaults is: who determines what is sensible?

Let's take startTime for arguments sake. The first-time user (consumer) of the service, I can't know what data the provider has available to me, and therefore cannot know what is sensible. And what is sensible for the consumer 1 doesn't mean that it is sensible for consumer 2 and it might be not at all sensible for provider X. Sensible might be even scenario-based.

startTime therefore cannot be mandatory (unless you like to guess) and a sensible default depends on the circumstances.

However, the behaviour of the default should be defined as part of the standard and be implemented as such. So, in this case, probably the documentation should specify that when startTime is missing, the first startTime in the system is to be retrieved.

This should apply to all parameters: define usage and behaviour.

[gerritsj]

I agree with your comments. Indeed, defining a sensible default is not trivial. However, the question then is what the response should be if no startTime or endTime are specified for coverages/{coverageId}/data. The first startTime or the last endTime in the system is not viable because of the large amount of data the system may have.

[GeriWolters]

I can think of several solutions, but they would probably require a lot of work. The easiest, perhaps is the following: the paging-block elements (previous, next and self) should always specify all query parameters. In case of optional parameters which were not specified, they must specify the values the API itself used.

So parameters can be optional the first time they were specified on the original URL, but during the round trip they get filled with the values used by the provider. Paging information (page number, page size) actually already work this way.

[gerritsj]

Yes, paging is generally an option, but not if the response is a netCDF-file containing the data.

[GeriWolters]

http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/cf-conventions.html#description-of-file-contents defines that you can place comments in the cf-netcdf file. Suggestion: use the comment field to supply structured data concerning the parameter used to produce the file. Would that be an option?

[stefhummel]

(During team discussion) If startTime and endTime both omitted: deliver values of last available time step If startTime provided, endTime omitted: deliver values from startTime to last available time step If startTime and endTime provided: deliver requested selection If startTime omitted, endTime provided: deliver values of endTime if available, otherwise provide values of of the last available time step before endTime

[stefhummel]

Note: Issue concerns all optional parameters. Specify defaults and behaviour for all other optional parameters

[stefhummel]

(After re-discussion in team) We concluded that the most straight forward approach is: make startTime and endTime mandatory. Very clear, and no implementation obligations for the implementing systems.