Part 4: Define which submission types for jobs are actually needed

[m-mohr]

There are so many options to get async/sync results from /jobs and /jobs/:id/results. It should probably be limited to a small subset so that there are not X options for "the same thing.

Discussion started in #437 (comment)_

[fmigneault]

The current execution modes are:

1. sync | jobControlOptions: execute-sync
   (technically OAP's default)

   • POST /jobs + Prefer: wait={seconds}: starts execution right away, responds with results 200
   • returns the results inline from the first request (no extra request required)
   • if desired, results could be retrieved again at GET /jobs/{jobId}/results

2. async | jobControlOptions: execute-async
   (could be a default if supported: Part 4: Clarify that default execution mode is at discretion of backend #449 (comment))

   • POST /jobs + Prefer: respond-async: job queued immediately, responds a Job Status 201
   • starts whenever resources are available, results might be ready, but could be at a later time
   • once completed, results must be retrieved at GET /jobs/{jobId}/results

3. create | jobControlOptions TBD
   (see Part 4: Clarify that default execution mode is at discretion of backend #449 (comment))
   (openEO's default)

   • POST /jobs + status: create: job is created but awaits trigger to be queued, responds Job Status 201
   • POST /jobs/{jobId}/results: places the job in queue, executes whenever resources are available
     (return 202?, see Part 4: Allow job start to return 202 instead of 200 #461)
   • once completed, results must be retrieved at GET /jobs/{jobId}/results

#437 (comment) also proposed that (3) could consider whatever Prefer header at the same time as status: create, such that once triggered, sync or async could be applied.

[fmigneault]

Meeting on 2024-10-31

Suggestions:

• using queue: bool instead of status: "create" in body
• using an X-OGC-Queue (or similar) header
• using the Prefer header with a custom respond-queued mode

Decisions

• a header for job control will be used instead of status/queue body parameter
  This is to make it easier to transition POST /processes/{processID}/execution to /jobs with a simpler server redirect (easier to inject the header than rewrite the body contents)
• given the OAP 2.0 being developed, make openEO's non-queued approach the default
  (i.e.: Prefer: respond-queued or similar if omitted)

Still to decide/under discussion

• Default execution mode (sync/async) when not queued right away
  (relates to Default execution mode should be asynchronous. #413)
  Should the server (not OAP specification) be the one to decide what is the default if the process description advertises it supports both modes?

[m-mohr]

Just wondering, we only discussed header and body parameters for the queue parameter. Could it also be a query parameter? It feels easier to use and define than a new header.

[fmigneault]

It technically could, but I'm personally not fond of POST requests using query parameters simultaneously with body contents. It adds complexity for clients and servers having to cross-check multiple places. Users are more often used to GET+query or POST+body for submitting searches/operations, so I would prefer to keep them distinct methods.

[m-mohr]

Fair enough. Header is fine, too.