1.0.0-rc.1 implementation issues

[m-mohr]

As I'm currently implementing 1.0.0-rc.1 for GEE, here's a list of what came up:

General

• 1. The CHANGELOG is not complete. Fixed in 1e67bd0
• 2. It is not clear how back-end should react on a limit parameter if they don't support pagination (error vs. return the full list). Fixed in f1a7bb7
• 3. The JSON Schema for process graph validation is invalid (used from_argument instead of from_parameter). Fixed in 1c3e4ed
• 4. Update STAC from 0.9.0 RC1 to 0.9.0 (RC2) if required, there were some minor changes.
• 5. offset parameter is missing from logs endpoints. See PR Reintroduced the missing offset parameter for log endpoints #263
• 6. Clarify which instance is the default instance to connect to, Fixed in 2856cd5, see also issue Clarify default instance to connect to #259.

Related to process graphs (user-defined processes)

• A. Sending process graphs to /services, /jobs and /result is lacking the default values from the parameters that are available in /process_graphs. This may lead to issues during execution when user hasn't specified the parameters. See PR Pass process metadata with data processing requests #262
• B. GET /process_graphs: Field id is not required for the processes. Fixed in 05bc778
• C. POST /process_graphs is not following REST. It should be PUT /process_graphs/{process_graph_id} as we actually set the id ourself. From docs it's also not 100% clear whether the process graph id (e.g. in the path) is the same as a process id. See PR PUT /process_graphs/{id} #261
• D. PATCH /process_graphs/{process_graph_id} allows to change the id, but the behavior afterwards is unclear. In theory the path must change. I tend to forbid changing the ID. See PR PUT /process_graphs/{id} #261
• E. Usually in responses like GET /jobs/{job_id} or GET /services/{service_id} most (all?) optional fields can be set to null, which makes implementation a bit easier. For the process graphs at /process_graphs none of the fields can be set to null and so they must actually be missing from the response if no data is available. That's more difficult to implement, but aligned with /processes. Should we introduce nullable for some/all fields in /process_graphs and/or /processes? For more information see issue Make optional fields nullable in process-related endpoints? #264.
• F. Related to E: As you can't set null in PATCH /process_graphs/{process_graph_id} you can't easily "reset" fields. For example, you can only remove the description by sending an empty string. For parameters you'd need to send am empty object, but that means "no parameters" where as not having parameters at all means the parameters are simply unknown/unspecified, but there may be some. See PR PUT /process_graphs/{id} #261

We may head for a quick 1.0.0-rc.2 as I guess there wasn't much work put into 1.0.0-rc.1 implementations yet.

[m-mohr]

Ideas:

1. For A there are two options:
   • Replace property process_graph with process in request bodies and then pass the full metadata of a process if available? See PR Pass process metadata with data processing requests #262
   • Let clients send the default values, which they need to extract from the process metadata.
2. For C, D and F:
   • POST /process_graphs and PATCH /process_graphs/:id with a single endpoint PUT /process_graphs/:id. id can't be changed as it's part of the path. See PR PUT /process_graphs/{id} #261
3. For E:
   • Allow null in optional fields in /process_graphs and /processes.
   • Leave as is and deal with the additional implementation effort.

@jdries @soxofaan @lforesta @aljacob @kempenep @flahn