Jobs and services: Define creation parameters #276

[m-mohr]

GET /jobs and GET /services: Added create_parameters property in responses to define the parameters that can be submitted when creating jobs or services.

I'm not 100% sure whether adding these parameters to GET /jobs and GET /services is ideal as they would always be served whenever a job/service list will be served or paginated. We could also add the data to two new endpoints.

Implements #276

[soxofaan]

I'm not 100% sure whether adding these parameters to GET /jobs and GET /services is ideal as they would always be served whenever a job/service list will be served or paginated. We could also add the data to two new endpoints.

Indeed, I also find it strange to add this to the endpoints were we currently list actual jobs/services.
Can't we just add this to the general capabilities doc / ?
We already list some request aspects there anyway, like

  "endpoints": [
...
    {
      "methods": [ "GET", "POST"],
      "path": "/jobs"
    },
    {
      "methods": ["GET", "DELETE"],
      "path": "/jobs/{job_id}"
    },
...

[m-mohr]

I'm hesistant to add it there to keep it simple/small and not delay the request too much, because it's the first one and should not block additional requests because it needs to wait for some options to be retrieved. We also have /service_types externally for this reason.

[soxofaan]

to keep it simple/small and not delay the request too much,

maybe I'm misunderstanding, but I don't think a reasonable implementation of the API will be delayed by adding a couple of fields the the capabilities document.

[soxofaan]

I get that it feels normal from the web editor point of view, because you probably list a user's jobs before they are able to create a new one.

But in case of less interactive or lazy client environments like python client usage: it's a bit weird that the client first has to request GET /jobs in order to create a new job.

[m-mohr]

No, I think you understood correctly, but I also assumed that with other endpoints and it did turnout that this was a false assumption. So maybe we just add a new endpoint that returns these options (then likely called job_create_parameters and service_create_parameters or so).

[m-mohr]

I've updated the PR to have a dedicated (optional) endpoint.

[m-mohr]

This PR only specifies what happens for POST requests (reflected in descriptions and field names create_...), but doesn't say anything about update. -> todo

[soxofaan]

Couple of slightly related notes/questions:

• are the defaults global or can they depend on user (e.g. subscription level or some other property)?
• is it allowed to use a default like null in the public parameter specification which allows the backend to use a an actual fallback value that is not public or dynamic in some sense (e.g. user dependent, dependent on current cluster load, automatically derived from spatial/temporal extent, ...)?
• is it necessary to cover these concerns in the description?

[m-mohr]

Moved this from 1.2.0 to 1.3.0. Implementors are free to implement this proposal and give feedback, but it didn't feel fully fleshed out yet for a release in 1.2.0.