From f47c072ca41315b32ed4910797aef167e965ff57 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 3 May 2023 17:37:14 +0200 Subject: [PATCH] Clarified ambiguous batch job status changes (#444) * Clarified ambiguous batch job status changes. * Update openapi.yaml Co-authored-by: Stefaan Lippens * Allow back-ends to not restart. --------- Co-authored-by: Stefaan Lippens --- CHANGELOG.md | 1 + openapi.yaml | 31 ++++++++++++++++++------------- 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7b2c2a22..23093c42 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -52,6 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Clarify that the relation type `version-history` should include `/.well-known/openeo` in the URL. - Clarify that clients should (re-)request capabilities and discovery endpoints with token if available and supported. [#416](https://github.com/Open-EO/openeo-api/issues/416) - Clarify the fields `plan` (for processing requests) and `billing_plan` (in `GET /` and `GET /me`). [#425](https://github.com/Open-EO/openeo-api/issues/425) [#426](https://github.com/Open-EO/openeo-api/issues/426) +- Clarified ambiguous batch job status changes. - Reflect that the `debug` process has been renamed to `inspect`. - Clarified uniqueness constraints for identifiers. [#449](https://github.com/Open-EO/openeo-api/issues/449) [#454](https://github.com/Open-EO/openeo-api/issues/454) - Clarified schematically the applicability of JSON Schema extensions (`parameters`, `returns`, `dimensions`) and their relation to the subtypes diff --git a/openapi.yaml b/openapi.yaml index 90378bb7..030d9791 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2976,13 +2976,14 @@ paths: patch: summary: Modify a batch job operationId: update-job - description: >- + description: |- Modifies an existing job at the back-end, but maintains the identifier. Changes can be grouped in a single request. + The job status does not change. - Jobs can only be modified when the job is not queued or running. - Otherwise requests to this endpoint MUST be rejected with openEO error + Jobs can only be modified when the job is not queued and not running. + Otherwise, requests to this endpoint MUST be rejected with openEO error `JobLocked`. tags: - Data Processing @@ -3371,12 +3372,12 @@ paths: The result will be stored in the format specified in the process. To specify the format use a process such as `save_result`. - This endpoint has no effect if the job status is already `queued` or - `running`. In particular, it doesn't restart a running job. Processing - MUST be canceled before to restart it. - The job status is set to `queued`, if processing doesn't start - instantly. + instantly. The same applies if the job status is `canceled`, `finished`, + or `error`, which restarts the job and discards previous results if the + back-end doesn't reject the request with an error. + Clients SHOULD warn users and ask for confirmation if results may get + discarded. * Once the processing starts the status is set to `running`. * Once the data is available to download the status is set to @@ -3384,6 +3385,10 @@ paths: * Whenever an error occurs during processing, the status MUST be set to `error`. + This endpoint has no effect if the job status is already `queued` or + `running`. In particular, it doesn't restart a running job. To restart + a queued or running job, processing MUST have been canceled before. + Back-ends SHOULD reject queueing jobs with openEO error `PaymentRequired`, if the back-end is able to detect that the budget is too low to fully process the request. Alternatively, back-ends MAY provide partial results @@ -3405,20 +3410,20 @@ paths: delete: summary: Cancel processing a batch job operationId: stop-job - description: >- + description: |- Cancels all related computations for this job at the back-end. It will stop generating additional costs for processing. - A subset of processed results may be available for downloading depending - on the state of the job as it was canceled. Finished results MUST NOT be - deleted until the job is deleted or job processing is started again. + on the state of the job at the time it was canceled. + Results MUST NOT be deleted until the job processing is started again or + the job is completely deleted through a request to + `DELETE /jobs/{job_id}`. This endpoint only has an effect if the job status is `queued` or `running`. - The job status is set to `canceled` if the status was `running` beforehand and partial or preliminary results are available to be downloaded. Otherwise the status is set to `created`.