Improvements regarding signed URLs (#380)

* Improvements for issue #379

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `GET /credentials/oidc` can provide a set of default client ids for OpenID Connect. [#366](https://github.com/Open-EO/openeo-api/pull/366)
 - `experimental` and `deprecated` flags added for file formats, service types, udf runtimes, udf runtime versions, udf runtime libraries and all related parameters and schemas. [#354](https://github.com/Open-EO/openeo-api/issues/354)
 - `GET /jobs/{job_id}/logs` and `GET /services/{service_id}/logs`: `time` property added. [#330](https://github.com/Open-EO/openeo-api/issues/330)
+- Added error `ResultLinkExpired`.  [#379](https://github.com/Open-EO/openeo-api/issues/379)
 
 ### Changed
 
@@ -22,6 +23,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Clarified how process exceptions should be used. [#352](https://github.com/Open-EO/openeo-api/issues/352)
 - Clarified that billing plans, service names and file formats must be accepted case-insensitive. [#371](https://github.com/Open-EO/openeo-api/issues/371)
 - Clarified that the first provider listed at `GET /credentials/oidc` is the default provider for OpenID Connect.
+- Clarified that `GET /jobs/{job_id}/results` should always return valid signed URLs and the endpoint can be used to renew the signed URLs. [#379](https://github.com/Open-EO/openeo-api/issues/379)
 - Fixed casing of potential endpoints `GET /collections/{collection_id}/items` and `GET /collections/{collection_id}/items/{feature_id}`.
 
 ## 1.0.1 - 2020-12-07

errors.json

@@ -290,6 +290,14 @@
 			"Batch Jobs"
 		]
 	},
+	"ResultLinkExpired": {
+		"description": "The signed URLs for batch job results have expired. Please send a request to `GET /jobs/{job_id}/results` to refresh the links.",
+		"message": "The link to the batch job result has expired. Please request the results again.",
+		"http": 410,
+		"tags": [
+			"Batch Jobs"
+		]
+	},
 	"PaymentRequired": {
 		"description": "The budget required to fulfil the request is insufficient.",
 		"message": "The budget required to fulfil the request is not sufficient. A payment is required first.",

openapi.yaml

@@ -2980,26 +2980,27 @@ paths:
     get:
       summary: Download results for a completed batch job
       operationId: list-results
-      description: >-
+      description: |-
         Lists signed URLs pointing to the processed files after the batch job
         has finished. Back-ends may also point to intermediate results after the
         job has stopped due to an error.
-        
 
         The response includes additional metadata. It is a valid
-        [STAC Item (version 0.9.0)](https://github.com/radiantearth/stac-spec/tree/v0.9.0/item-spec)
+        [STAC Item](https://github.com/radiantearth/stac-spec/tree/v0.9.0/item-spec)
         if it has spatial and temporal references included.
 
-
         URL signing is a way to protect files from unauthorized access with a
         key in the URL instead of HTTP header based authorization. The URL
         signing key is similar to a password and its inclusion in the URL allows
         to download files using simple GET requests supported by a wide range of
         programs, e.g. web browsers or download managers. Back-ends are
         responsible to generate the URL signing keys and to manage their
         appropriate expiration. The back-end MAY indicate an expiration time by
-        setting the `expires` property.
-
+        setting the `expires` property in the reponse. Requesting this endpoint
+        SHOULD always return non-expired URLs. Signed URLs that were generated
+        for a previous request and already expired SHOULD NOT be reused,
+        but regenerated with new expiration time.
+        Signed URLs that expired MAY return the openEO error `ResultLinkExpired`.
 
         If processing has not finished yet requests to this endpoint MUST be
         rejected with openEO error `JobNotFinished`.