Several improvements for estimates, budget and costs #443

CHANGELOG.md

@@ -30,6 +30,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Updated STAC specification examples and references to v1.0.0.
 - `cube:dimensions`: `reference_system` is allowed to be PROJJSON, too. 
 - Relaxed requirement that unsupported endpoints must return HTTP status code 501. Instead also HTTP status code 404 can be used (and is regularly used in practice). [#415](https://github.com/Open-EO/openeo-api/issues/415)
+- Minimum value for `costs` and `budget` is 0.
+- `GET /jobs/{job_id}/estimate`: If a batch job can't be estimated reliably, a `EstimateComplexity` error should be returned. [#443](https://github.com/Open-EO/openeo-api/issues/443)
 
 ### Fixed
 
@@ -43,6 +45,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `GET /`: Removed the superfluous default value for `currency`. [#423](https://github.com/Open-EO/openeo-api/issues/423)
 - Reflect that the `debug` process has been renamed to `inspect`.
 - `GET /credentials/oidc`: Clarify that clients may add additional scopes
+- `GET /me`: Clarify the behavior of the field `budget`.
+- `GET /jobs/{job_id}/estimate`: Don't require that the costs are the upper limit. Services may specify the costs more freely depending on their terms of service.
 - 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)
 
 ## [1.1.0] - 2021-05-17

errors.json

@@ -66,6 +66,14 @@
 			"Data Processing"
 		]
 	},
+	"EstimateComplexity": {
+		"description": "The process is too complex to calculate an estimate, e.g. due to a UDF or other processes that are complex to estimate costs reliably.",
+		"message": "The process is too complex to calculate an estimate.",
+		"http": 500,
+		"tags": [
+			"Batch Jobs"
+		]
+	},
 	"NoDataForUpdate": {
 		"description": "For PATCH requests: No valid data specified at all.",
 		"message": "No data specified to be updated.",

openapi.yaml

@@ -2973,12 +2973,20 @@ paths:
       description: >-
         Calculates an estimate for a batch job. Back-ends can decide to
         either calculate the duration, the costs, the size or a combination of
-        them. This MUST be the upper limit of the incurring costs. Clients can
-        be charged less than specified, but never more. Back-end providers MAY
-        specify an expiry time for the estimate. Starting to process data
-        afterwards MAY be charged at a higher cost. Costs MAY NOT include
-        downloading costs. This can be indicated with the `downloads_included`
-        flag.
+        them.
+
+        Back-end providers MAY specify an expiry time for the estimate.
+        Starting to process data afterwards MAY be charged at a higher cost.
+        Costs MAY NOT include downloading costs. This can be indicated with the
+        `downloads_included` flag.
+
+        The estimate SHOULD be the upper limit of the costs, but back-end are
+        free to use the field according to their terms of service.
+
+        For some batch jobs it is not (easily) possible to estimate the costs
+        reliably, e.g. if a user-submitted UDF is part of the process.
+        In this case, the server SHOULD return a `EstimateComplexity` error
+        with HTTP status code 500.
       tags:
         - Data Processing
         - Batch Jobs
@@ -3565,7 +3573,12 @@ paths:
                           to the user.
                         example: 1073741824
                   budget:
-                    $ref: '#/components/schemas/budget'
+                    type: number
+                    nullable: true
+                    description: |-
+                      The remaining budget a user has available.
+                      The value MUST be specified in the currency of the back-end.
+                      The value SHOULD be set to `null` if no explicit limit applies.
                   links:
                     description: |-
                       Links related to the user profile, e.g. where payments
@@ -4095,11 +4108,13 @@ components:
         currency the back-end is working with. The currency can be retrieved by
         calling `GET /`. If no currency is set, this field MUST be `null`.
       type: number
+      minimum: 0
       example: 12.98
       nullable: true
       default: null
     budget:
       type: number
+      minimum: 0
       nullable: true
       description: |-
         Maximum amount of costs the request is allowed to produce.
@@ -4110,6 +4125,7 @@ components:
       default: null
     budget_update:
       type: number
+      minimum: 0
       nullable: true
       description: |-
         Maximum amount of costs the request is allowed to produce.