From dd7428d9183646a369f82539544b2ab88edee8b0 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 25 May 2023 11:17:08 +0200 Subject: [PATCH 01/52] Update changelog date for 1.2.0 --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bced4c98..020a1c35 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased / Draft -## [1.2.0] - 2021-05-31 +## [1.2.0] - 2021-05-25 ### Added From 2396ac11b2d7564e14b12080807891d20f699825 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 7 Jul 2023 17:27:01 +0200 Subject: [PATCH 02/52] Fix that file format parameters show datacube and process parameter subtypes --- CHANGELOG.md | 4 ++++ openapi.yaml | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 020a1c35..ddfeaf2c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased / Draft +### Fixed + +- `GET /file_formats`: Base paramater on top of normal JSON Schema, not Process JSON Schema + ## [1.2.0] - 2021-05-25 ### Added diff --git a/openapi.yaml b/openapi.yaml index aafd67fc..29f68527 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -5813,7 +5813,7 @@ components: the same level. For example, if type is string, then default can be "foo" but cannot be 1. See [JSON Schema draft-07](https://json-schema.org/draft-07/json-schema-validation.html#rfc.section.10.2). allOf: - - $ref: '#/components/schemas/process_json_schema' + - $ref: '#/components/schemas/json_schema' error: title: General Error description: >- From 814c3867087f04aeb5f2320c49a3a213d8406e34 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 12 Jul 2023 16:05:29 +0200 Subject: [PATCH 03/52] Clarifications in extensions --- extensions/commercial-data/README.md | 2 +- extensions/federation/README.md | 20 ++++++++++++++------ 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/extensions/commercial-data/README.md b/extensions/commercial-data/README.md index 3fe7c177..191bd5d8 100644 --- a/extensions/commercial-data/README.md +++ b/extensions/commercial-data/README.md @@ -155,7 +155,7 @@ Example request payload to `GET /search` for `PLEIADES` products from "Living Li ### Ordering products -Backends should implement the following endpoints: +Backends must implement the following endpoints: - `GET /orders`: Get a list of all created orders - `POST /orders`: Create an order diff --git a/extensions/federation/README.md b/extensions/federation/README.md index 16e0d2ae..9343f0ab 100644 --- a/extensions/federation/README.md +++ b/extensions/federation/README.md @@ -155,8 +155,19 @@ schema: ## Resources supported only by a subset of back-ends -Every discoverable resource that is defined as an object and allows to contain additional properties, can list the backends that support or host the exposed resource/functionality. -This can also be embeded deeply into a hierarchical structure, e.g. for process or file format parameters. +Every discoverable resource that is defined as an object and allows to contain additional properties, can list the backends that support or host the exposed resource/functionality. Examples of where this could apply to (**not** comprehensive): + +- `GET /collections/{id}` +- `GET /processes` (per process, per parameter) +- `GET /file_formats` (per file format) +- `GET /udf_runtimes` (per UDF runtime, per version) +- `POST /validation` (the back-ends that can run the process) +- `GET /process_graphs/{id}` +- `GET /jobs/{job_id}` (the back-ends that generated the result) +- `GET /jobs/{job_id}/results` (the back-ends that generated the result) +- `GET /services/{id}` + +This can also be embedded deeply into a hierarchical structure, e.g. for process or file format parameters. ```yaml schema: @@ -207,10 +218,7 @@ schema: "stac_version": "1.0.0", "id": "example", "description": "...", - "summaries": { - "federation:backends": ["vito", "eodc"], - ... - }, + "federation:backends": ["vito", "eodc"], ... } ``` \ No newline at end of file From 9555433eb8829f5524a5f2ef6c66d9dd69c8742b Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 14 Jul 2023 13:50:29 +0200 Subject: [PATCH 04/52] `PATCH /services/{service_id}` and `PATCH /jobs/{job_id}`: Explicitly allow updating back-end specific properties (as in `POST`) `GET /services/{service_id}` and `GET /jobs/{job_id}`: Explicitly allow listing back-end specific properties (as provided in `POST`) --- CHANGELOG.md | 2 ++ openapi.yaml | 10 +++++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ddfeaf2c..fb557834 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed - `GET /file_formats`: Base paramater on top of normal JSON Schema, not Process JSON Schema +- `PATCH /services/{service_id}` and `PATCH /jobs/{job_id}`: Explicitly allow updating back-end specific properties (as in `POST`) +- `GET /services/{service_id}` and `GET /jobs/{job_id}`: Explicitly allow listing back-end specific properties (as provided in `POST`) ## [1.2.0] - 2021-05-25 diff --git a/openapi.yaml b/openapi.yaml index 29f68527..966bdbcb 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2789,6 +2789,8 @@ paths: $ref: '#/components/schemas/budget_update' log_level: $ref: '#/components/schemas/min_log_level_update' + additionalProperties: + description: You can add additional back-end specific properties here. description: The data to change for the specified secondary web service. get: summary: Full metadata for a service @@ -2810,7 +2812,9 @@ paths: - configuration - attributes allOf: - - $ref: '#/components/schemas/service' + - $ref: '#/components/schemas/service' + additionalProperties: + description: You can list additional back-end specific properties here. 4XX: $ref: '#/components/responses/client_error_auth' 5XX: @@ -3017,6 +3021,8 @@ paths: $ref: '#/components/schemas/budget_update' log_level: $ref: '#/components/schemas/min_log_level_update' + additionalProperties: + description: You can add additional back-end specific properties here. description: Specifies the job details to update. get: summary: Full metadata for a batch job @@ -3038,6 +3044,8 @@ paths: - process allOf: - $ref: '#/components/schemas/batch_job' + additionalProperties: + description: You can list additional back-end specific properties here. 4XX: $ref: '#/components/responses/client_error_auth' 5XX: From cecc3f49733362aa7672cdd96f1fc08d1c81559b Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 11 Oct 2023 17:30:08 +0200 Subject: [PATCH 05/52] Minor updates to wording and tooling --- extensions/commercial-data/README.md | 2 +- extensions/commercial-data/openapi.yaml | 8 ++++---- extensions/commercial-data/package.json | 6 +++--- openapi.yaml | 2 +- package.json | 2 +- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/extensions/commercial-data/README.md b/extensions/commercial-data/README.md index 191bd5d8..6e6ae84a 100644 --- a/extensions/commercial-data/README.md +++ b/extensions/commercial-data/README.md @@ -1,6 +1,6 @@ # Commercial Data Extension -The Commercial Data API extension provides an interface for discovering, ordering and using commercial data in the openEO API. +The Commercial Data Extension to the openEO API provides an interface for discovering, ordering and using commercial data in openEO. - Version: **0.1.0** - Stability: **experimental** diff --git a/extensions/commercial-data/openapi.yaml b/extensions/commercial-data/openapi.yaml index c2c2d1a2..00506f60 100644 --- a/extensions/commercial-data/openapi.yaml +++ b/extensions/commercial-data/openapi.yaml @@ -1,10 +1,10 @@ openapi: 3.0.2 info: - title: openEO Commercial Data API extension + title: openEO API - Commercial Data Extension version: 0.1.0 description: >- - The Commercial Data API extension provides an interface for discovering, - ordering and using commercial data in the openEO API. + The Commercial Data Extension to the openEO API provides an interface for discovering, + ordering and using commercial data in openEO. contact: name: openEO Consortium url: 'https://openeo.org' @@ -13,7 +13,7 @@ info: name: Apache 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0.html' externalDocs: - url: https://github.com/Open-EO/openeo-api/blob/draft/extensions/federation/README.md + url: https://github.com/Open-EO/openeo-api/blob/draft/extensions/commercial-data/README.md tags: - name: Orders description: Management of commercial data orders diff --git a/extensions/commercial-data/package.json b/extensions/commercial-data/package.json index 0fd067ed..aa9bc101 100644 --- a/extensions/commercial-data/package.json +++ b/extensions/commercial-data/package.json @@ -13,12 +13,12 @@ "url": "git+https://github.com/Open-EO/openeo-api.git" }, "devDependencies": { - "@stoplight/spectral": "^5.9.1", - "redoc-cli": "^0.13.18" + "@stoplight/spectral": "^6.6.0", + "redoc-cli": "^0.13.21" }, "scripts": { "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", - "build": "redoc-cli bundle openapi.yaml -o redoc.html --title \"openEO API\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", + "build": "redoc-cli bundle openapi.yaml -o redoc.html --title \"openEO API - Commercial Data Extension\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", "test": "spectral lint openapi.yaml" } } diff --git a/openapi.yaml b/openapi.yaml index 966bdbcb..7e9a7984 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2751,7 +2751,7 @@ paths: operationId: update-service description: |- Modifies an existing secondary web service at the back-end, - but maintain the identifier. Changes can be grouped in a single request. + but maintains the identifier. Changes can be grouped in a single request. User have to create a new service to change the service type. tags: diff --git a/package.json b/package.json index 8a19865b..dbbb4094 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,7 @@ }, "devDependencies": { "@stoplight/spectral-cli": "^6.6.0", - "redoc-cli": "^0.13.18" + "redoc-cli": "^0.13.21" }, "scripts": { "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", From e40ad4a3b6d9a3b6f651338ccb6cfbce829a4c6b Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 12 Oct 2023 01:40:00 +0200 Subject: [PATCH 06/52] Enable tests for commercial data extension --- .github/workflows/tests.yml | 7 ++++++- extensions/commercial-data/.spectral.yml | 12 ++++++++++++ extensions/commercial-data/package.json | 2 +- 3 files changed, 19 insertions(+), 2 deletions(-) create mode 100644 extensions/commercial-data/.spectral.yml diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 64b0febd..9345633d 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -8,7 +8,12 @@ jobs: with: node-version: 'lts/*' - uses: actions/checkout@v3 - - name: Run tests + - name: Run core tests run: | + npm install + npm test + - name: Run commercial-data tests + run: | + cd extensions/commercial-data npm install npm test \ No newline at end of file diff --git a/extensions/commercial-data/.spectral.yml b/extensions/commercial-data/.spectral.yml new file mode 100644 index 00000000..ad10553b --- /dev/null +++ b/extensions/commercial-data/.spectral.yml @@ -0,0 +1,12 @@ +extends: "spectral:oas" +rules: + contact-properties: true + tag-description: true + oas3-parameter-description: true + oas3-unused-component: true + operation-id-kebab-case: + given: "$..operationId" + then: + function: pattern + functionOptions: + match: ^[a-z][a-z0-9\-]*$ \ No newline at end of file diff --git a/extensions/commercial-data/package.json b/extensions/commercial-data/package.json index aa9bc101..87e80dfa 100644 --- a/extensions/commercial-data/package.json +++ b/extensions/commercial-data/package.json @@ -13,7 +13,7 @@ "url": "git+https://github.com/Open-EO/openeo-api.git" }, "devDependencies": { - "@stoplight/spectral": "^6.6.0", + "@stoplight/spectral-cli": "^6.6.0", "redoc-cli": "^0.13.21" }, "scripts": { From 476b78a46be788c9a1f0bd64b3c6b9d0ab6e6c9f Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 11 Oct 2023 17:34:50 +0200 Subject: [PATCH 07/52] First draft --- .github/workflows/tests.yml | 5 + extensions/workspaces/.spectral.yml | 12 + extensions/workspaces/README.md | 16 ++ extensions/workspaces/openapi.yaml | 410 ++++++++++++++++++++++++++++ extensions/workspaces/package.json | 24 ++ openapi.yaml | 28 +- 6 files changed, 483 insertions(+), 12 deletions(-) create mode 100644 extensions/workspaces/.spectral.yml create mode 100644 extensions/workspaces/README.md create mode 100644 extensions/workspaces/openapi.yaml create mode 100644 extensions/workspaces/package.json diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 9345633d..52364fe1 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -16,4 +16,9 @@ jobs: run: | cd extensions/commercial-data npm install + npm test + - name: Run workspaces tests + run: | + cd extensions/workspaces + npm install npm test \ No newline at end of file diff --git a/extensions/workspaces/.spectral.yml b/extensions/workspaces/.spectral.yml new file mode 100644 index 00000000..ad10553b --- /dev/null +++ b/extensions/workspaces/.spectral.yml @@ -0,0 +1,12 @@ +extends: "spectral:oas" +rules: + contact-properties: true + tag-description: true + oas3-parameter-description: true + oas3-unused-component: true + operation-id-kebab-case: + given: "$..operationId" + then: + function: pattern + functionOptions: + match: ^[a-z][a-z0-9\-]*$ \ No newline at end of file diff --git a/extensions/workspaces/README.md b/extensions/workspaces/README.md new file mode 100644 index 00000000..b2a92614 --- /dev/null +++ b/extensions/workspaces/README.md @@ -0,0 +1,16 @@ +# Workspaces Extension + +The Workspace Extension to the openEO API provides an interface for connecting external file storage such as cloud buckets to openEO back-end implementations. + +This opens the possibility to register such a file storage system as a data source for new collections, so-called "User Collections". +Additionally, batch job results can be stored on such file storage systems. + +- Version: **0.1.0** +- Stability: **experimental** +- [OpenAPI document](openapi.yaml) +- Conformance class: `https://api.openeo.org/extensions/workspaces/0.1.0` + +**Note:** This document only documents the additions to the specification. +Extensions can not change or break existing behavior of the openEO API. + +The Workspace API is inspired by the [EOEPCA Workspace API](https://github.com/EOEPCA/rm-workspace-api) with regards to workspace management. The User Collections are not aligned with EOEPCA. \ No newline at end of file diff --git a/extensions/workspaces/openapi.yaml b/extensions/workspaces/openapi.yaml new file mode 100644 index 00000000..5d22fd34 --- /dev/null +++ b/extensions/workspaces/openapi.yaml @@ -0,0 +1,410 @@ +openapi: 3.0.2 +info: + title: openEO API - Workspaces Extension + version: 0.1.0 + description: |- + The Workspace Extension to the openEO API provides an interface for connecting external file storage such as cloud buckets to openEO back-end implementations. + + This opens the possibility to register such a file storage system as a data source for new collections, so-called "User Collections". + Additionally, batch job results can be stored on such file storage systems. + + The Workspace API is inspired by the [EOEPCA Workspace API](https://github.com/EOEPCA/rm-workspace-api) with regards to workspace management. The User Collections are not aligned with EOEPCA. + contact: + name: openEO Consortium + url: 'https://openeo.org' + email: openeo.psc@uni-muenster.de + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' +externalDocs: + url: https://github.com/Open-EO/openeo-api/blob/draft/extensions/workspaces/README.md +tags: + - name: Workspaces + description: Management of User Workspaces + - name: User Collections + description: Management of User Collections +servers: + - url: 'https://openeo.example/api/{version}' + description: >- + The URL of the API MAY freely be chosen by the back-end providers. The + path, including API versioning, is a *recommendation* only. Nevertheless, + all servers MUST support HTTPS as the authentication methods are not + secure with HTTP only! + variables: + version: + default: v1 + description: >- + API versioning is RECOMMENDED. As the openEO API is following + [SemVer](https://semver.org/) only the MAJOR part of the stable + version numbers (i.e. versions >= 1.0.0) SHOULD be used for API + versioning in the URL. The reason is that backward-incompatible + changes are usually introduced by major changes. Therefore, the + version number in the URL MUST not be used by the clients to detect + the version number of the API. Use the version number returned from + `GET /` instead. +paths: + /workspaces: + get: + summary: List all workspaces + operationId: list-workspaces + description: |- + Lists all workspaces that have been added by a user. + + It is **strongly RECOMMENDED** to keep the response size small by + omitting all optional non-scalar values (i.e. arrays and objects) from objects in `workspaces`. + To get the full metadata for a workspace clients MUST request `GET /workspaces/{workspace_id}`. + tags: + - Workspaces + security: + - Bearer: [] + parameters: + - $ref: '../../openapi.yaml#/components/parameters/pagination_limit' + responses: + '200': + description: Array of workspace descriptions + content: + application/json: + schema: + title: Workspaces + type: object + required: + - workspaces + - links + properties: + workspaces: + type: array + items: + $ref: '#/components/schemas/workspace' + links: + $ref: '../../openapi.yaml#/components/schemas/links_pagination' + 4XX: + $ref: '../../openapi.yaml#/components/responses/client_error_auth' + 5XX: + $ref: '../../openapi.yaml#/components/responses/server_error' + post: + summary: Create Workspace + operationId: create-workspace + description: |- + Creates a new workspace. + + This request queues the creation of a workspace. It directly registers an id at the back-end, but the workspace itself may have a status of `provisioning` until the workspace is ready to use. + tags: + - Workspaces + security: + - Bearer: [] + requestBody: + content: + application/json: + schema: + type: object + required: + - intent + properties: + intent: + type: string + quota: + $ref: '../../openapi.yaml#/components/schemas/max_storage_quota' + oneOf: + - title: Create workspace + properties: + intent: + enum: + - create + example: create + - title: Register existing workspace + required: + - url + - credentials + properties: + intent: + enum: + - register + example: register + url: + $ref: '#/components/schemas/workspace_url' + credentials: + $ref: '#/components/schemas/workspace_credentials' + required: true + responses: + '201': + description: The workspace creation has been queued successfully. + headers: + Location: + required: true + schema: + description: |- + Absolute URL to the workspace metadata. + + The URL points to the endpoint + `GET /workspaces/{workspace_id}` with the `{workspace_id}` being the + id of the created workspace. + format: uri + type: string + example: 'https://openeo.example/api/v1/workspaces/my-workspace' + OpenEO-Identifier: + required: true + schema: + $ref: '#/components/schemas/workspace_id' + 4XX: + $ref: '../../openapi.yaml#/components/responses/client_error_auth' + 5XX: + $ref: '../../openapi.yaml#/components/responses/server_error' + /workspaces/{workspace_id}: + parameters: + - $ref: '#/components/parameters/workspace_id' + get: + summary: Full metadata for a workspace + operationId: describe-workspace + description: >- + Returns the full metadata for a workspace. + tags: + - Workspaces + security: + - Bearer: [] + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/workspace' + 4XX: + $ref: '../../openapi.yaml#/components/responses/client_error_auth' + 5XX: + $ref: '../../openapi.yaml#/components/responses/server_error' + delete: + summary: Delete Workspace + operationId: delete-workspace + description: |- + Removes the workspace from the backend. + + Associated User Collections MAY also be removed. + tags: + - Workspaces + security: + - Bearer: [] + responses: + '204': + description: The workspace has been successfully deleted. + 4XX: + $ref: '../../openapi.yaml#/components/responses/client_error_auth' + 5XX: + $ref: '../../openapi.yaml#/components/responses/server_error' + patch: + summary: Update workspace details + operationId: update-workspace + description: >- + Updates the workspace details. + tags: + - Workspaces + security: + - Bearer: [] + requestBody: + content: + application/json: + schema: + type: object + properties: + quota: + $ref: '../../openapi.yaml#/components/schemas/max_storage_quota' + required: true + responses: + '204': + description: Changes to the workspace were applied successfully. + 4XX: + $ref: '../../openapi.yaml#/components/responses/client_error_auth' + 5XX: + $ref: '../../openapi.yaml#/components/responses/server_error' + /collections: + post: + summary: Create a new User Collection + operationId: create-collection + description: |- + Registers a new collection. + + The data must be available in the workspace provided via the query parameter. The data must be a STAC catalog in the given https://github.com/Open-EO/openeo-api/blob/draft/extensions/workspaces/README.md + + The default entry point is a `catalog.json` or `collection.json` in the "root folder". The entry point can be customized by providing a relative link with the relation type `entrypoint` in the STAC metadata. + + The collection metadata is provided via the request body. If no `id` is specified, the back-end assigns an ID. + tags: + - User Collections + - Workspaces + security: + - Bearer: [] + parameters: + - name: workspace + in: query + required: true + description: The ID of the workspace where the data for the collection is located. + schema: + $ref: '#/components/schemas/workspace_id' + requestBody: + required: true + description: |- + The metadata to use for the specified User Collection. + + **TODO:** The schema describes a generic collection. Required fields don't apply. + content: + application/json: + schema: + $ref: '../../openapi.yaml#/components/schemas/collection' + responses: + '201': + description: The collection has been created successfully. + headers: + Location: + required: true + schema: + description: |- + Absolute URL to the newly created collection. + + The URL points to the metadata endpoint + `GET /collections/{collection_id}` with the `{collection_id}` being the + id of the created collection. + format: uri + type: string + example: 'https://openeo.example/api/v1/collections/my-collection' + OpenEO-Identifier: + required: true + schema: + $ref: '../../openapi.yaml#/components/schemas/collection_id' + 4XX: + $ref: '../../openapi.yaml#/components/responses/client_error_auth' + 5XX: + $ref: '../../openapi.yaml#/components/responses/server_error' + /collections/{collection_id}: + parameters: + - $ref: '../../openapi.yaml#/components/parameters/collection_id' + patch: + summary: Modify a User Collection + operationId: update-collection + description: |- + Modifies an existing User Collection at the back-end, + but maintains the identifier and associated workspace. Changes can be grouped in a single request. + + User have to create a new collection to change the associated workspace or the collection identifier. + tags: + - User Collections + security: + - Bearer: [] + responses: + '204': + description: Changes to the User Collection were applied successfully. + 4XX: + $ref: '../../openapi.yaml#/components/responses/client_error_auth' + 5XX: + $ref: '../../openapi.yaml#/components/responses/server_error' + requestBody: + required: true + description: |- + The metadata to change for the specified User Collection. + + **TODO:** The schema describes a generic collection. Required fields don't apply. The `id` can't be updated. + content: + application/json: + schema: + $ref: '../../openapi.yaml#/components/schemas/collection_id' + delete: + summary: Delete a User Collection + operationId: delete-collection + description: |- + Deletes the User Collection. + + Does NOT delete jobs or services that reference this User Collection. Also, does NOT remove any data from the workspace or the workspace itself. + tags: + - User Collections + security: + - Bearer: [] + responses: + '204': + description: The User Collection has been successfully deleted + 4XX: + $ref: '../../openapi.yaml#/components/responses/client_error_auth' + 5XX: + $ref: '../../openapi.yaml#/components/responses/server_error' +components: + parameters: + workspace_id: + name: workspace_id + in: path + required: true + description: The ID of the workspace. + schema: + $ref: '#/components/schemas/workspace_id' + schemas: + workspace_id: + type: string + pattern: '^[\w\-\.~]+$' + example: my-collection + workspace: + title: Workspace + required: + - id + - status + type: object + properties: + id: + $ref: '#/components/schemas/workspace_id' + status: + type: string + description: The status of the workspace. + details: + type: string + description: >- + A status message (e.g. error message) or any other free-text information about the workspace. + quota: + $ref: '../../openapi.yaml#/components/schemas/max_storage_quota' + oneOf: + - title: Unavailable + description: + The workspace is not available, e.g. because it's still provisioning it + or the back-end can't connect to it / lost the connection / has been deleted externally, ... + properties: + status: + enum: + - provisioning + - unavailable + example: provisioning + - title: Ready + properties: + status: + enum: + - ready + example: ready + url: + $ref: '#/components/schemas/workspace_url' + credentials: + $ref: '#/components/schemas/workspace_credentials' + properties: + $ref: '#/components/schemas/workspace_properties' + free: + $ref: '../../openapi.yaml#/components/schemas/storage_quota_free' + workspace_url: + type: string + format: uri + description: The URL of the actual workspace, e.g. a bucket URL. + example: 'https://my-bucket.s3.eu-west-3.amazonaws.com' + workspace_credentials: + type: object + description: >- + Credentials to access the workspace as required by the workspace provider. + The structure is not specified by the API. + additionalProperties: + type: string + example: + username: john_doe + password: secret123 + workspace_properties: + type: object + description: >- + Any additional metadata of the workspace provided by the workspace provider. + The structure is not specified by the API. + additionalProperties: + description: Any type + example: + region: eu-west-3 + storage_class: standard + securitySchemes: + Bearer: + $ref: '../../openapi.yaml#/components/securitySchemes/Bearer' diff --git a/extensions/workspaces/package.json b/extensions/workspaces/package.json new file mode 100644 index 00000000..08897e2f --- /dev/null +++ b/extensions/workspaces/package.json @@ -0,0 +1,24 @@ +{ + "name": "@openeo/api-extension-commercial-data", + "version": "0.1.0", + "author": "openEO Consortium", + "license": "Apache-2.0", + "description": "The openEO API specification.", + "homepage": "https://openeo.org", + "bugs": { + "url": "https://github.com/Open-EO/openeo-api/issues" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/Open-EO/openeo-api.git" + }, + "devDependencies": { + "@stoplight/spectral-cli": "^6.6.0", + "redoc-cli": "^0.13.21" + }, + "scripts": { + "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", + "build": "redoc-cli bundle openapi.yaml -o redoc.html --title \"openEO API - Workspace Extension\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", + "test": "spectral lint openapi.yaml" + } +} diff --git a/openapi.yaml b/openapi.yaml index 7e9a7984..ee119cb3 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3667,19 +3667,9 @@ paths: - quota properties: free: - type: integer - description: >- - Free storage space in bytes, which is still available - to the user. Effectively, this is the disk quota minus - the used space by the user, e.g. user-uploaded files - and job results. - example: 536870912 + $ref: '#/components/schemas/storage_quota_free' quota: - type: integer - description: >- - Maximum storage space (disk quota) in bytes available - to the user. - example: 1073741824 + $ref: '#/components/schemas/max_storage_quota' budget: type: number nullable: true @@ -4280,6 +4270,20 @@ components: example: free nullable: true default: null + storage_quota_free: + type: integer + description: >- + Free storage space in bytes, which is still available + to the user. Effectively, this is the disk quota minus + the used space by the user, e.g. user-uploaded files + and job results. + example: 536870912 + max_storage_quota: + type: integer + description: >- + Maximum storage space (disk quota) in bytes available + to the user. + example: 1073741824 collection: title: Collection type: object From 9eb872ed65002900e6dd950e7977e8d58812db9d Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 1 Dec 2023 10:51:20 +0100 Subject: [PATCH 08/52] Add title and description to workspaces, removed updating the quota --- extensions/workspaces/openapi.yaml | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/extensions/workspaces/openapi.yaml b/extensions/workspaces/openapi.yaml index 5d22fd34..9a06bb96 100644 --- a/extensions/workspaces/openapi.yaml +++ b/extensions/workspaces/openapi.yaml @@ -100,6 +100,10 @@ paths: required: - intent properties: + title: + $ref: '#/components/schemas/workspace_title' + description: + $ref: '#/components/schemas/workspace_description' intent: type: string quota: @@ -205,8 +209,10 @@ paths: schema: type: object properties: - quota: - $ref: '../../openapi.yaml#/components/schemas/max_storage_quota' + title: + $ref: '#/components/schemas/workspace_title' + description: + $ref: '#/components/schemas/workspace_description' required: true responses: '204': @@ -337,6 +343,17 @@ components: type: string pattern: '^[\w\-\.~]+$' example: my-collection + workspace_title: + type: string + description: A short title for the workspace. + workspace_description: + type: string + format: commonmark + description: |- + A description that describes the workspace. + + [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich + text representation. workspace: title: Workspace required: @@ -346,6 +363,10 @@ components: properties: id: $ref: '#/components/schemas/workspace_id' + title: + $ref: '#/components/schemas/workspace_title' + description: + $ref: '#/components/schemas/workspace_description' status: type: string description: The status of the workspace. From 829bc79a9180979d56bdc8cc78cf695a694f394d Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 8 Dec 2023 15:02:39 +0100 Subject: [PATCH 09/52] Remove user collections --- extensions/workspaces/README.md | 7 +- extensions/workspaces/openapi.yaml | 121 +---------------------------- extensions/workspaces/package.json | 2 +- 3 files changed, 6 insertions(+), 124 deletions(-) diff --git a/extensions/workspaces/README.md b/extensions/workspaces/README.md index b2a92614..1d1be677 100644 --- a/extensions/workspaces/README.md +++ b/extensions/workspaces/README.md @@ -1,9 +1,6 @@ # Workspaces Extension -The Workspace Extension to the openEO API provides an interface for connecting external file storage such as cloud buckets to openEO back-end implementations. - -This opens the possibility to register such a file storage system as a data source for new collections, so-called "User Collections". -Additionally, batch job results can be stored on such file storage systems. +The Workspace Extension to the openEO API provides an interface for connecting external file storage such as cloud buckets to openEO back-end implementations. This allows for example to store batch job results on such file storage systems. - Version: **0.1.0** - Stability: **experimental** @@ -13,4 +10,4 @@ Additionally, batch job results can be stored on such file storage systems. **Note:** This document only documents the additions to the specification. Extensions can not change or break existing behavior of the openEO API. -The Workspace API is inspired by the [EOEPCA Workspace API](https://github.com/EOEPCA/rm-workspace-api) with regards to workspace management. The User Collections are not aligned with EOEPCA. \ No newline at end of file +The Workspace API is inspired by the [EOEPCA Workspace API](https://github.com/EOEPCA/rm-workspace-api) with regards to workspace management. \ No newline at end of file diff --git a/extensions/workspaces/openapi.yaml b/extensions/workspaces/openapi.yaml index 9a06bb96..9bfab4b3 100644 --- a/extensions/workspaces/openapi.yaml +++ b/extensions/workspaces/openapi.yaml @@ -3,12 +3,9 @@ info: title: openEO API - Workspaces Extension version: 0.1.0 description: |- - The Workspace Extension to the openEO API provides an interface for connecting external file storage such as cloud buckets to openEO back-end implementations. + The Workspace Extension to the openEO API provides an interface for connecting external file storage such as cloud buckets to openEO back-end implementations. This allows for example to store batch job results on such file storage systems. - This opens the possibility to register such a file storage system as a data source for new collections, so-called "User Collections". - Additionally, batch job results can be stored on such file storage systems. - - The Workspace API is inspired by the [EOEPCA Workspace API](https://github.com/EOEPCA/rm-workspace-api) with regards to workspace management. The User Collections are not aligned with EOEPCA. + The Workspace API is inspired by the [EOEPCA Workspace API](https://github.com/EOEPCA/rm-workspace-api) with regards to workspace management. contact: name: openEO Consortium url: 'https://openeo.org' @@ -21,8 +18,6 @@ externalDocs: tags: - name: Workspaces description: Management of User Workspaces - - name: User Collections - description: Management of User Collections servers: - url: 'https://openeo.example/api/{version}' description: >- @@ -181,8 +176,6 @@ paths: operationId: delete-workspace description: |- Removes the workspace from the backend. - - Associated User Collections MAY also be removed. tags: - Workspaces security: @@ -221,114 +214,6 @@ paths: $ref: '../../openapi.yaml#/components/responses/client_error_auth' 5XX: $ref: '../../openapi.yaml#/components/responses/server_error' - /collections: - post: - summary: Create a new User Collection - operationId: create-collection - description: |- - Registers a new collection. - - The data must be available in the workspace provided via the query parameter. The data must be a STAC catalog in the given https://github.com/Open-EO/openeo-api/blob/draft/extensions/workspaces/README.md - - The default entry point is a `catalog.json` or `collection.json` in the "root folder". The entry point can be customized by providing a relative link with the relation type `entrypoint` in the STAC metadata. - - The collection metadata is provided via the request body. If no `id` is specified, the back-end assigns an ID. - tags: - - User Collections - - Workspaces - security: - - Bearer: [] - parameters: - - name: workspace - in: query - required: true - description: The ID of the workspace where the data for the collection is located. - schema: - $ref: '#/components/schemas/workspace_id' - requestBody: - required: true - description: |- - The metadata to use for the specified User Collection. - - **TODO:** The schema describes a generic collection. Required fields don't apply. - content: - application/json: - schema: - $ref: '../../openapi.yaml#/components/schemas/collection' - responses: - '201': - description: The collection has been created successfully. - headers: - Location: - required: true - schema: - description: |- - Absolute URL to the newly created collection. - - The URL points to the metadata endpoint - `GET /collections/{collection_id}` with the `{collection_id}` being the - id of the created collection. - format: uri - type: string - example: 'https://openeo.example/api/v1/collections/my-collection' - OpenEO-Identifier: - required: true - schema: - $ref: '../../openapi.yaml#/components/schemas/collection_id' - 4XX: - $ref: '../../openapi.yaml#/components/responses/client_error_auth' - 5XX: - $ref: '../../openapi.yaml#/components/responses/server_error' - /collections/{collection_id}: - parameters: - - $ref: '../../openapi.yaml#/components/parameters/collection_id' - patch: - summary: Modify a User Collection - operationId: update-collection - description: |- - Modifies an existing User Collection at the back-end, - but maintains the identifier and associated workspace. Changes can be grouped in a single request. - - User have to create a new collection to change the associated workspace or the collection identifier. - tags: - - User Collections - security: - - Bearer: [] - responses: - '204': - description: Changes to the User Collection were applied successfully. - 4XX: - $ref: '../../openapi.yaml#/components/responses/client_error_auth' - 5XX: - $ref: '../../openapi.yaml#/components/responses/server_error' - requestBody: - required: true - description: |- - The metadata to change for the specified User Collection. - - **TODO:** The schema describes a generic collection. Required fields don't apply. The `id` can't be updated. - content: - application/json: - schema: - $ref: '../../openapi.yaml#/components/schemas/collection_id' - delete: - summary: Delete a User Collection - operationId: delete-collection - description: |- - Deletes the User Collection. - - Does NOT delete jobs or services that reference this User Collection. Also, does NOT remove any data from the workspace or the workspace itself. - tags: - - User Collections - security: - - Bearer: [] - responses: - '204': - description: The User Collection has been successfully deleted - 4XX: - $ref: '../../openapi.yaml#/components/responses/client_error_auth' - 5XX: - $ref: '../../openapi.yaml#/components/responses/server_error' components: parameters: workspace_id: @@ -342,7 +227,7 @@ components: workspace_id: type: string pattern: '^[\w\-\.~]+$' - example: my-collection + example: my-workspace workspace_title: type: string description: A short title for the workspace. diff --git a/extensions/workspaces/package.json b/extensions/workspaces/package.json index 08897e2f..05b2a0f1 100644 --- a/extensions/workspaces/package.json +++ b/extensions/workspaces/package.json @@ -1,5 +1,5 @@ { - "name": "@openeo/api-extension-commercial-data", + "name": "@openeo/api-extension-workspaces", "version": "0.1.0", "author": "openEO Consortium", "license": "Apache-2.0", From 82102c37745421dda7e0c4462809caee8516e936 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 17 Jan 2024 15:01:59 +0100 Subject: [PATCH 10/52] Add missing conformance class for STAC API Core to example --- openapi.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/openapi.yaml b/openapi.yaml index 7e9a7984..bd566aea 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3752,6 +3752,7 @@ components: - https://api.openeo.org/1.2.0 - https://api.openeo.org/extensions/commercial-data/0.1.0 - https://api.openeo.org/extensions/federation/0.1.0 + - https://api.stacspec.org/v1.0.0/core - https://api.stacspec.org/v1.0.0/collections udf_runtime: type: object From 6ea99c3ae4ab342c54f9cd39a7403085fa6ca79f Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 17 Jan 2024 16:22:57 +0100 Subject: [PATCH 11/52] Clarified for log levels which default values apply --- CHANGELOG.md | 1 + openapi.yaml | 5 +++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fb557834..fdd0e0eb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `GET /file_formats`: Base paramater on top of normal JSON Schema, not Process JSON Schema - `PATCH /services/{service_id}` and `PATCH /jobs/{job_id}`: Explicitly allow updating back-end specific properties (as in `POST`) - `GET /services/{service_id}` and `GET /jobs/{job_id}`: Explicitly allow listing back-end specific properties (as provided in `POST`) +- Clarified for log levels which default values apply ## [1.2.0] - 2021-05-25 diff --git a/openapi.yaml b/openapi.yaml index bd566aea..93eff76d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -5895,7 +5895,8 @@ components: The order of the levels is as follows (from low to high severity): `debug`, `info`, `warning`, `error`. That means if `warning` is set, the back-end will only store log entries with the level `warning` and `error`. - The default minimum log level is `info`. Users need to specifically set this property to `debug` to get *all* log entries. + The default minimum log level is `info`. + Users need to specifically set this property to `debug` to capture *all* log entries. It is RECOMMENDED that users set the level at least to "warning" in production workflows. type: string enum: @@ -6626,7 +6627,7 @@ components: - warning - info - debug - default: info + default: debug service_id: name: service_id in: path From 7d40f9d7274db69e4c70239108e3c4d2948eed6a Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 8 Feb 2024 21:56:08 +0100 Subject: [PATCH 12/52] Editorial changes based on OGC review (#525) --- openapi.yaml | 204 +++++++++++++++++++++++++-------------------------- 1 file changed, 101 insertions(+), 103 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 93eff76d..bf98aec3 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -13,21 +13,21 @@ info: In the specification the key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.html) and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174.html). - ## Casing + ## Literal Case Unless otherwise stated the API works **case sensitive**. - All names SHOULD be written in snake case, i.e. words are separated with one underscore character (`_`) and no spaces, with all letters lower-cased. Example: `hello_world`. This applies particularly to endpoints and JSON property names. HTTP header fields are generally case-insensitive according to [RFC 7230](https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2) and in the specification we follow their respective casing conventions, e.g. `Content-Type` or `OpenEO-Costs`, for better readability and consistency. + All names SHOULD be written in snake case, i.e. words are separated with one underscore character (`_`) and no spaces, with all letters lower-cased. Example: `hello_world`. This applies particularly to endpoints and JSON property names. HTTP header fields are generally case-insensitive according to [RFC 7230](https://www.rfc-editor.org/rfc/rfc7230.html#section-3.2) and their respective casing conventions are followed, e.g. `Content-Type` or `OpenEO-Costs`, for better readability and consistency. ## HTTP / REST - This uses [HTTP REST](https://en.wikipedia.org/wiki/Representational_state_transfer) [Level 2](https://martinfowler.com/articles/richardsonMaturityModel.html#level2) for communication between client and back-end server. + This specification uses [HTTP REST](https://en.wikipedia.org/wiki/Representational_state_transfer) [Level 2](https://martinfowler.com/articles/richardsonMaturityModel.html#level2) for communication between client and back-end server. - Public APIs MUST be available via HTTPS only. + Public API implementations MUST be available via HTTPS only. - Endpoints are made use meaningful HTTP verbs (e.g. GET, POST, PUT, PATCH, DELETE) whenever technically possible. If there is a need to transfer big chunks of data for a GET requests to the back-end, POST requests MAY be used as a replacement as they support to send data via request body. Unless otherwise stated, PATCH requests are only defined to work on direct (first-level) children of the full JSON object. Therefore, changing a property on a deeper level of the full JSON object always requires to send the whole JSON object defined by the first-level property. + Endpoints are made use meaningful HTTP verbs (e.g. GET, POST, PUT, PATCH, DELETE) whenever technically possible. If there is a need to transfer big chunks of data for a GET requests to the back-end, POST requests MAY be used as a replacement as they support to send data via request body. Unless otherwise stated, PATCH requests are only defined to work on direct (first-level) children of the full JSON object. Therefore, changing a property on a deeper level of the full JSON object always requires sending the whole JSON object defined by the first-level property. - Naming of endpoints follow the REST principles. Therefore, endpoints are centered around resources. Resource identifiers MUST be named with a noun in plural form except for single actions that can not be modelled with the regular HTTP verbs. Single actions MUST be single endpoints with a single HTTP verb (POST is RECOMMENDED) and no other endpoints beneath it. + Naming rules of the API endpoints follow the REST principles. Therefore, endpoints are centered around resources. Resource identifiers MUST be named with a noun in plural form except for single actions that can not be modelled with the regular HTTP verbs. Single actions MUST be single endpoints with a single HTTP verb (POST is RECOMMENDED) and no other endpoints beneath it. The openEO API makes use of [HTTP Content Negotiation](https://www.rfc-editor.org/rfc/rfc9110.html#name-content-negotiation), including, but not limited to, the request headers `Accept`, `Accept-Charset` and `Accept-Language`. @@ -38,30 +38,30 @@ info: ### Charset - Services use [UTF-8](https://en.wikipedia.org/wiki/UTF-8) as the default charset if not negotiated otherwise with HTTP Content Negotiation ([`Accept-Charset` header](https://www.rfc-editor.org/rfc/rfc9110.html#name-accept-charset)). + If not negotiated otherwise with HTTP Content Negotiation ([`Accept-Charset` header](https://www.rfc-editor.org/rfc/rfc9110.html#name-accept-charset)), services use [UTF-8](https://en.wikipedia.org/wiki/UTF-8) as the default charset. ## Web Linking - The API is designed in a way that to most entities (e.g. collections and processes) a set of links can be added. These can be alternate representations, e.g. data discovery via OGC WCS or OGC CSW, references to a license, references to actual raw data for downloading, detailed information about pre-processing and more. Clients should allow users to follow the links. + The API is designed in a way that for most resources, such as collections and processes, a set of links can be added. These can be alternate representations such as data discovery via OGC WCS or OGC CSW, references to a license, references to actual raw data for downloading, detailed information about pre-processing and more. Clients should allow users to follow the links. Whenever links are utilized in the API, the description explains which relation (`rel` property) types are commonly used. A [list of standardized link relations types is provided by IANA](https://www.iana.org/assignments/link-relations/link-relations.xhtml) and the API tries to align whenever feasible. Some very common relation types - usually not mentioned explicitly in the description of `links` fields - are: - 1. `self`: which allows link to the location that the resource can be (permanently) found online.This is particularly useful when the data is data is made available offline, so that the downstream user knows where the data has come from. + 1. `self`: Refers to the location that the resource can be (permanently) found online. This is particularly useful when the data is made available offline, so that the downstream user knows the source of the data. 2. `alternate`: An alternative representation of the resource, may it be another metadata standard the data is available in or simply a human-readable version in HTML or PDF. - 3. `about`: A resource that is related or further explains the resource, e.g. a user guide. + 3. `about`: A resource that is related to or further explains the resource, e.g. a user guide. 4. `canonical`: This relation type usually points to a publicly accessible and more long-lived URL for a resource that otherwise often requires (Bearer) authentication with a short-lived token. - This way the the exposed resources can be used by non-openEO clients without additional authentication steps. + This way the exposed resources can be used by non-openEO clients without additional authentication steps. For example, a shared user-defined process or batch job results could be exposed via a canonical link. If a URL should be publicly available to everyone, it can simply a user-specific URL, e.g. `https://openeo.example/processes/john_doe/ndvi`. For resources that should only be accessible to a certain group of user, a signed URL could be given, e.g. `https://openeo.example/processes/81zjh1tc2pt52gbx/ndvi`. - Generally, it is RECOMMENDED to add descriptive titles (propertty `title`) and media type information (propertty `type`) for a better user experience. + Generally, it is RECOMMENDED adding descriptive titles (propertty `title`) and media type information (propertty `type`) for a better user experience. ## Error Handling @@ -92,7 +92,7 @@ info: * The `code` is either one of the [standardized textual openEO error codes](errors.json) or a proprietary error code. * The `message` explains the reason the server is rejecting the request. For "4xx" error codes the message explains how the client needs to modify the request. - By default the message MUST be sent in English language. Content Negotiation is used to localize the error messages: If an `Accept-Language` header is sent by the client and a translation is available, the message should be translated accordingly and the `Content-Language` header must be present in the response. See "[How to localize your API](http://apiux.com/2013/04/25/how-to-localize-your-api/)" for more information. + By default, the message MUST be in English. Content Negotiation is used to localize the error messages: If an `Accept-Language` header is sent by the client and a translation is available, the message should be translated accordingly, and the `Content-Language` header must be present in the response. See "[How to localize your API](http://apiux.com/2013/04/25/how-to-localize-your-api/)" for more information. * `url` is an OPTIONAL attribute and contains a link to a resource that is explaining the error and potential solutions in-depth. ### Standardized status codes @@ -108,7 +108,7 @@ info: - **204 No Content**: Indicates a successful request **without** a response body being sent. - The openEO API has some commonly used HTTP status codes for failed requests: + The openEO API reuses commonly used HTTP status codes for failed requests: - **400 Bad Request**: The back-end responds with this error code whenever the error has its origin on client side and no other HTTP status code in the 400 range is suitable. @@ -117,11 +117,11 @@ info: The client did not provide any authentication details for a resource requiring authentication or the provided authentication details are not correct. - **403 Forbidden**: - The client did provided correct authentication details, but the privileges/permissions of the provided credentials do not allow to request the resource. + The client did provide correct authentication details, but the privileges/permissions of the provided credentials do not allow requesting the resource. - **404 Not Found**: - The resource specified by the path does not exist, i.e. one of the resources belonging to the specified identifiers are not available at the back-end. - *Note:* Unsupported endpoints MAY also return HTTP status code 501. + The resource specified by the path does not exist. One of the resources belonging to the specified identifiers are not available at the back-end. + *Note:* Unsupported endpoints MAY also return an HTTP status code 501. - **500 Internal Server Error**: The error has its origin on server side and no other status code in the 500 range is suitable. @@ -131,13 +131,13 @@ info: *Note:* Unsupported endpoints MAY also return HTTP status code 404. - If a HTTP status code in the 400 range is returned, the client SHOULD NOT repeat the request without modifications. For HTTP status code in the 500 range, the client MAY repeat the same request later. + If a HTTP status code in the 400 range is returned, the client SHOULD modify the request and repeat the request. For HTTP status code in the 500 range, the client MAY repeat the same request later. All HTTP status codes defined in RFC 7231 in the 400 and 500 ranges can be used as openEO error code in addition to the most used status codes mentioned here. Responding with openEO error codes 400 and 500 SHOULD be avoided in favor of any more specific standardized or proprietary openEO error code. ## Temporal data - Date, time, intervals and durations are formatted based on ISO 8601 or its profile [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) whenever there is an appropriate encoding available in the standard. All temporal data are specified based on the Gregorian calendar. + Date, time, time intervals, and durations are formatted based on ISO 8601 or its profile [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) whenever there is an appropriate encoding available in the standard. All temporal data are specified based on the Gregorian calendar. # Authentication @@ -151,19 +151,19 @@ info: - **Note:** Although it is possible to request several public endpoints for capabilities and discovery that don't require authorization, it is RECOMMENDED that clients (re-)request the public endpoints that support Bearer authentication with the Bearer token once available to also retrieve any private data that is made available specifically for the authenticated user. + **Note:** Although it is possible to request several public endpoints for capabilities and discovery that do not require authorization, it is RECOMMENDED that clients (re-)request the public endpoints that support Bearer authentication with the Bearer token once available to also retrieve any private data that is made available specifically for the authenticated user. This may require that clients clear any cached data they retrieved from public endpoints before. # Cross-Origin Resource Sharing (CORS) > Cross-origin resource sharing (CORS) is a mechanism that allows restricted resources [...] on a web page to be requested from another domain outside the domain from which the first resource was served. [...] - > CORS defines a way in which a browser and server can interact to determine whether or not it is safe to allow the cross-origin request. It allows for more freedom and functionality than purely same-origin requests, but is more secure than simply allowing all cross-origin requests. + > CORS defines a way in which a browser and server can interact to determine whether it is safe to allow the cross-origin request. This allows for more freedom and functionality than purely same-origin requests, but is more secure than simply allowing all cross-origin requests. Source: [https://en.wikipedia.org/wiki/Cross-origin_resource_sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) - openEO-based back-ends are usually hosted on a different domain / host than the client that is requesting data from the back-end. Therefore most requests to the back-end are blocked by all modern browsers. This leads to the problem that the JavaScript library and any browser-based application can't access back-ends. Therefore, all back-end providers SHOULD support CORS to enable browser-based applications to access back-ends. [CORS is a recommendation of the W3C organization](https://www.w3.org/TR/cors/). The following chapters will explain how back-end providers can implement CORS support. + openEO-based back-ends are usually hosted on a different domain / host than the client that is requesting data from the back-end. Therefore, most requests to the back-end are blocked by all modern browsers. This leads to the problem that the JavaScript library and any browser-based application can not access back-ends. Therefore, all back-end providers SHOULD support CORS to enable browser-based applications to access back-ends. [CORS is a recommendation of the W3C organization](https://www.w3.org/TR/cors/). The following chapters explain how back-end providers can implement CORS support. - **Tip**: Most servers can send the required headers and the responses to the OPTIONS requests automatically for all endpoints. Otherwise you may also use a proxy server to add the headers and OPTIONS responses. + **Tip**: Most servers can send the required headers and the responses to the OPTIONS requests automatically for all endpoints. Otherwise, a proxy server may be used to add the headers and OPTIONS responses. ## CORS headers @@ -171,8 +171,8 @@ info: | Name | Description | Example | | -------------------------------- | ------------------------------------------------------------ | ------- | - | Access-Control-Allow-Origin | Allowed origin for the request, including protocol, host and port or `*` for all origins. It is RECOMMENDED to return the value `*` to allow requests from browser-based implementations such as the Web Editor. | `*` | - | Access-Control-Expose-Headers | Some endpoints require to send additional HTTP response headers such as `OpenEO-Identifier` and `Location`. To make these headers available to browser-based clients, they MUST be white-listed with this CORS header. The following HTTP headers are white-listed by browsers and MUST NOT be included: `Cache-Control`, `Content-Language`, `Content-Length`, `Content-Type`, `Expires`, `Last-Modified` and `Pragma`. At least the following headers MUST be listed in this version of the openEO API: `Link`, `Location`, `OpenEO-Costs` and `OpenEO-Identifier`. | `Link, Location, OpenEO-Costs, OpenEO-Identifier` | + | Access-Control-Allow-Origin | Allowed origin for the request, including protocol, host and port or `*` for all origins. Returning the value `*` to allow requests from browser-based implementations is RECOMMENDED. | `*` | + | Access-Control-Expose-Headers | Some endpoints require sending additional HTTP response headers such as `OpenEO-Identifier` and `Location`. To make these headers available to browser-based clients, they MUST be white-listed with this CORS header. The following HTTP headers are white-listed by browsers and MUST NOT be included: `Cache-Control`, `Content-Language`, `Content-Length`, `Content-Type`, `Expires`, `Last-Modified` and `Pragma`. At least the following headers MUST be listed in this version of the openEO API: `Link`, `Location`, `OpenEO-Costs` and `OpenEO-Identifier`. | `Link, Location, OpenEO-Costs, OpenEO-Identifier` | @@ -200,7 +200,7 @@ info: ## OPTIONS method - All endpoints must respond to the `OPTIONS` HTTP method. This is a response for the preflight requests made by web browsers before sending the actual request (e.g. `POST /jobs`). It needs to respond with a status code of `204` and no response body. + All endpoints defined in the API specification must additionally respond to the `OPTIONS` HTTP method. This is a response for the preflight requests made by web browsers before sending the actual request (e.g. `POST /jobs`). It needs to respond with a status code of `204` and no response body. **In addition** to the HTTP headers shown in the table above, the following HTTP headers MUST be included with every response to an `OPTIONS` request: | Name | Description | Example | @@ -484,7 +484,7 @@ externalDocs: url: 'https://openeo.org/documentation/1.0/' tags: - name: Capabilities - description: General information about the API implementation and other supported capabilities at the back-end. + description: General information about the API implementation and other supported capabilities provided by the back-end. - name: Account Management description: |- The following endpoints handle user profiles, accounting and authentication. See also [Authentication](#section/Authentication). In general, the openEO API only defines a minimum subset of user management and accounting functionality. It allows to @@ -533,14 +533,14 @@ tags: ### Provide data for download - If you'd like to provide your data for download in addition to offering the cloud processing service, you can implement the full STAC API. Therefore you can implement the endpoints `GET /collections/{collection_id}/items` and `GET /collections/{collection_id}/items/{feature_id}` to support retrieval of individual items. To benefit from the STAC ecosystem and allow searching for items you can also implement `POST /search` and `GET /search`. Further information can be found in the [STAC API repository](https://github.com/radiantearth/stac-spec/tree/v0.9.0/api-spec). + If you'd like to provide your data for download in addition to offering the cloud processing service, you can implement the full STAC API. Therefore, you can implement the endpoints `GET /collections/{collection_id}/items` and `GET /collections/{collection_id}/items/{feature_id}` to support retrieval of individual items. To benefit from the STAC ecosystem and allow searching for items you can also implement `POST /search` and `GET /search`. Further information can be found in the [STAC API repository](https://github.com/radiantearth/stac-spec/tree/v0.9.0/api-spec). ### API Extensions STAC API has several [extensions](https://stac-api-extensions.github.io) that can be implemented on top of the openEO API to enrich the API functionality, e.g. for searching. - name: Process Discovery description: |- - These endpoints allow to list the predefined processes that are available at the back-end. To list user-defined processes see '[User-Defined Processes](#tag/User-Defined-Processes)'. + The process discovery endpoints provide details about the predefined processes that are available at the back-end. To list user-defined processes see '[User-Defined Processes](#tag/User-Defined-Processes)'. - name: User-Defined Processes description: These endpoints allow to store and manage user-defined processes with their process graphs at the back-end. - name: Data Processing @@ -738,7 +738,7 @@ paths: billing related API functionalities, e.g. budgeting or estimates. - The absence of this property doesn't mean the back-end is + The absence of this property does not mean the back-end is necessarily free to use for all. Providers may choose to bill users outside of the API, e.g. with a monthly fee that is not depending on individual API interactions. @@ -753,7 +753,7 @@ paths: ISO-4217 or a back-end specific unit that is used for billing such as credits, tiles or CPU hours. If set to `null`, budget and costs are not supported - by the back-end and users can't be charged. + by the back-end and users can not be charged. type: string nullable: true example: USD @@ -1042,15 +1042,15 @@ paths: formats not available through GDAL may be defined centrally for openEO. Custom file formats or parameters MAY be defined. - The format descriptions must describe how the file formats relate to - data cubes. Input file formats must describe how the files have to be - structured to be transformed into data cubes. Output file formats must + The format descriptions MUST describe how the file formats relate to + data cubes. Input file formats MUST describe how the files have to be + structured to be transformed into data cubes. Output file formats MUST describe how the data cubes are stored at the back-end and how the resulting file structure looks like. Back-ends MUST NOT support aliases, for example it is not allowed to support `geotiff` instead of `gtiff`. Nevertheless, openEO Clients MAY - translate user input input for convenience (e.g. translate `geotiff` to + translate user input for convenience (e.g. translate `geotiff` to `gtiff`). Also, for a better user experience the back-end can specify a `title`. @@ -1102,7 +1102,7 @@ paths: output: GTiff: title: GeoTiff - description: Export to GeoTiff. Doesn't support cloud-optimized GeoTiffs (COGs) yet. + description: Export to GeoTiff. Does not support cloud-optimized GeoTiffs (COGs) yet. gis_data_types: - raster parameters: @@ -1188,7 +1188,7 @@ paths: description: |- Lists all conformance classes specified in various standards that the implementation conforms to. Conformance classes are commonly used in - all OGC APIs and the STAC API specification. openEO adds relatively + all OGC API standards and the STAC API specification. openEO adds relatively broadly defined conformance classes, especially for the extensions. Otherwise, the implemented functionality can usually be retrieved from the [capabilties](#tag/Capabilities/operation/capabilities) in openEO. @@ -1201,7 +1201,7 @@ paths: More details: - [STAC API](https://github.com/radiantearth/stac-api-spec), especially the conformance class "STAC API - Collections" - - [OGC APIs](https://ogcapi.ogc.org/) + - [OGC API standards](https://ogcapi.ogc.org/) tags: - Capabilities responses: @@ -1581,7 +1581,7 @@ paths: Lists **all** supported metadata filters (also called "queryables") for a specific collection. - This endpoint is compatible with endpoint defined in the STAC API extension + This endpoint is compatible with the endpoint defined in the STAC API extension [`filter`](https://github.com/stac-api-extensions/filter#queryables) and [OGC API - Features - Part 3: Filtering](https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/filtering). For a precise definition please follow those specifications. @@ -1911,7 +1911,7 @@ paths: description: >- The first provider in this list is the default provider for authentication. Clients can either pre-select or directly use the default provider for authentication - if the user doesn't specify a specific value. + if the user does not specify a specific value. minItems: 1 items: title: OpenID Connect Provider @@ -1988,7 +1988,7 @@ paths: As such, openEO clients SHOULD NOT store or cache default OpenID Connect client information for long term usage. A default OpenID Connect client is intended to simplify authentication for novice users. - For production use cases, it is RECOMMENDED to set up a dedicated OpenID Connect client. + Setting up a dedicated OpenID Connect client is RECOMMENDED for production-ready back-ends. uniqueItems: true items: title: Default OpenID Connect Client @@ -2281,7 +2281,7 @@ paths: log_level: $ref: '#/components/schemas/min_log_level_default' additionalProperties: - description: You can add additional back-end specific properties here. + description: Aditional back-end specific properties are allowed. /process_graphs: get: summary: List all user-defined processes @@ -2410,13 +2410,13 @@ paths: reused in other processes. If a process with the specified `process_graph_id` exists, the process - is fully replaced. The id can't be changed for existing user-defined + is fully replaced. The id can not be changed for existing user-defined processes. The id MUST be unique across its namespace. Partially updating user-defined processes is not supported. To simplify exchanging user-defined processes, the property `id` can be part of - the request body. If the values don't match, the value for `id` gets + the request body. If the values do not match, the value for `id` gets replaced with the value from the `process_graph_id` parameter in the path. tags: @@ -2477,7 +2477,7 @@ paths: reference) in the user-defined process that is used to compute web service results. The appropriate arguments MUST be provided to the user-defined process, - usually at runtime from the context of the web service, + usually at runtime from the context of the web service. For example, a map service such as a WMS would need to inject the spatial extent into the user-defined process so that the back-end can compute the corresponding tile correctly. @@ -2741,8 +2741,8 @@ paths: log_level: $ref: '#/components/schemas/min_log_level_default' additionalProperties: - description: You can add additional back-end specific properties here. - description: The base data for the secondary web service to create + description: Additional back-end specific properties are allowed. + description: The base data required to create the secondary web service. '/services/{service_id}': parameters: - $ref: '#/components/parameters/service_id' @@ -2751,9 +2751,9 @@ paths: operationId: update-service description: |- Modifies an existing secondary web service at the back-end, - but maintains the identifier. Changes can be grouped in a single request. + but maintains the identifier. Changes can be grouped into a single request. - User have to create a new service to change the service type. + User MUST create a new service to change the service type. tags: - Secondary Services security: @@ -2790,7 +2790,7 @@ paths: log_level: $ref: '#/components/schemas/min_log_level_update' additionalProperties: - description: You can add additional back-end specific properties here. + description: Additional back-end specific properties are allowed. description: The data to change for the specified secondary web service. get: summary: Full metadata for a service @@ -2824,9 +2824,9 @@ paths: operationId: delete-service description: >- Deletes all data related to this secondary web service. - Computations are stopped, computed results are deleted and access to - this is not possible any more. This service won't generate additional - costs. + Computations are stopped, computed results are deleted, and access to + this service is no longer possible. This service will not generate + additional costs. tags: - Secondary Services security: @@ -2918,7 +2918,7 @@ paths: Creates a new batch processing task (job) from one or more (chained) processes at the back-end. - Processing the data doesn't start yet. The job status gets initialized + Processing the data does not start yet. The job status gets initialized as `created` by default. tags: - Data Processing @@ -2972,7 +2972,7 @@ paths: log_level: $ref: '#/components/schemas/min_log_level_default' additionalProperties: - description: You can add additional back-end specific properties here. + description: Additional back-end specific properties are allowed. description: 'Specifies the job details, e.g. the user-defined process and billing details.' '/jobs/{job_id}': parameters: @@ -3022,7 +3022,7 @@ paths: log_level: $ref: '#/components/schemas/min_log_level_update' additionalProperties: - description: You can add additional back-end specific properties here. + description: Additional back-end specific properties are allowed. description: Specifies the job details to update. get: summary: Full metadata for a batch job @@ -3054,8 +3054,8 @@ paths: summary: Delete a batch job operationId: delete-job description: >- - Deletes all data related to this job. Computations are stopped and - computed results are deleted. This job won't generate additional costs + Deletes all data related to a given batch job. Computations are stopped and + computed results are deleted. This job will not generate additional costs for processing. tags: - Data Processing @@ -3201,7 +3201,7 @@ paths: [STAC Collection](https://github.com/radiantearth/stac-spec/tree/v1.0.0/collection-spec) (supported since openEO API version 1.1.0). The assets to download are in both cases available in the property `assets` - and have the same structure. All additional metadata is not strictly required + and have the same structure. Additional metadata is not strictly required to download the files, but are helpful for users to understand the data. STAC Collections can either (1) add all assets as collection-level assets or @@ -3233,8 +3233,8 @@ paths: but regenerated with new expiration time. Signed URLs that expired MAY return the openEO error `ResultLinkExpired`. - It is **strongly recommended** to add a link with relation type `canonical` - to the STAC Item or STAC Collection (see the `links` property for details). + Adding a link with relation type `canonical` to the STAC Item or STAC Collection + is STRONGLY RECOMMENDED (see the `links` property for details). If processing has not finished yet and the `partial` parameter is not set to `true` requests to this endpoint MUST be rejected with openEO error `JobNotFinished`. @@ -3259,7 +3259,7 @@ paths: responses: '200': description: >- - Valid download links have been returned. The download links doesn't + Valid download links have been returned. The download links does not necessarily need to be located under the API base url. headers: OpenEO-Costs: @@ -3358,7 +3358,7 @@ paths: $ref: '#/components/schemas/batch_job_result' '424': description: >- - The request can't be fulfilled as the batch job failed. This request + The request can not be fulfilled as the batch job failed. This request will deliver the last error message that was produced by the batch job. @@ -3380,10 +3380,10 @@ paths: The result will be stored in the format specified in the process. To specify the format use a process such as `save_result`. - The job status is set to `queued`, if processing doesn't start + The job status is set to `queued`, if processing does not start 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. + back-end does not reject the request with an error. Clients SHOULD warn users and ask for confirmation if results may get discarded. @@ -3394,8 +3394,8 @@ paths: `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. + `running`. In particular, it does not restart a running job. To restart + a queued or running job, processing MUST have been canceled. 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 @@ -3556,7 +3556,7 @@ paths: file at the path exists. - Folders are created once required by a file upload. Empty folders can't + Folders are created once required by a file upload. Empty folders can not be created. tags: - File Storage @@ -3607,7 +3607,7 @@ paths: summary: Information about the authenticated user operationId: describe-account description: >- - Lists information about the authenticated user, e.g. the user id. + Lists information about the authenticated user such as the user id. The endpoint MAY return the disk quota available to the user. The endpoint MAY also return links related to user management @@ -3692,7 +3692,7 @@ paths: Links related to the user profile, e.g. where payments are handled or the user profile could be edited. - It is RECOMMENDED to provide links with the following `rel` (relation) types: + Providing links with the following `rel` (relation) types is RECOMMENDED: 1. `payment`: A page where users can recharge their user account with money or credits. @@ -3738,7 +3738,7 @@ components: description: |- Lists all conformance classes specified in various standards that the implementation conforms to. Conformance classes are commonly used in - all OGC APIs and the STAC API specification. + all OGC API standards and the STAC API specification. The general openEO conformance class is `https://api.openeo.org/1.2.0`. See the individual openEO API extensions for their conformance classes. @@ -4252,7 +4252,7 @@ components: Back-ends MUST resolve the billing plan in the following way if billing is supported: * If a value is given and it is not `null`: Persist the `plan` that has been provided in the request. - * Otherwise, don't change the billing plan. + * Otherwise, do not change the billing plan. Billing plans not on the list of available plans MUST be rejected with openEO error `BillingPlanInvalid`. @@ -4427,8 +4427,7 @@ components: Could reference to licensing information, other meta data formats with additional information or a preview image. - It is RECOMMENDED to provide links with the following - `rel` (relation) types: + Providing links with the following `rel` (relation) types is RECOMMENDED: 1. `root` and `parent`: URL to the data discovery endpoint at `/collections`. @@ -5256,7 +5255,7 @@ components: description: |- Links related to this process, e.g. additional external documentation. - It is RECOMMENDED to provide links with the following `rel` (relation) types: + Providing links with the following `rel` (relation) types is RECOMMENDED: 1. `latest-version`: If a process has been marked as deprecated, a link SHOULD point to the preferred version of the process. The relation types `predecessor-version` @@ -5335,7 +5334,7 @@ components: This allows users to add missing predefined processes for portability, e.g. common processes from [processes.openeo.org](https://processes.openeo.org) that have a process graph included. - It is RECOMMENDED to log the namespace selected by the back-end for debugging purposes. + Logging the namespace selected by the back-end for debugging purposes is RECOMMENDED. * `backend`: Uses exclusively the predefined processes listed at `GET /processes`. * `user`: Uses exclusively the user-defined processes listed at `GET /process_graphs`. @@ -5375,7 +5374,7 @@ components: type: boolean description: >- Declares that the specified entity is experimental, which means that - it is likely to change or may produce unpredictable behaviour. Users + it is likely to change or may produce unpredictable behavior. Users should refrain from using it in production, but still feel encouraged to try it out and give feedback. default: false @@ -5449,7 +5448,7 @@ components: A list of parameters. The order in the array corresponds to the parameter order to - be used in clients that don't support named parameters. + be used in clients that do not support named parameters. **Note:** Specifying an empty array is different from (if allowed) `null` or the property being absent. @@ -5470,7 +5469,7 @@ components: description: |- A unique name for the parameter. - It is RECOMMENDED to use [snake case](https://en.wikipedia.org/wiki/Snake_case) (e.g. `window_size` or `scale_factor`). + Using [snake case](https://en.wikipedia.org/wiki/Snake_case) (e.g. `window_size` or `scale_factor`) is RECOMMENDED. pattern: '^\w+$' description: $ref: '#/components/schemas/process_description' @@ -5544,7 +5543,7 @@ components: The following status changes can occur: * `POST /jobs`: The status is initialized as `created`. * `POST /jobs/{job_id}/results`: The status is set to `queued`, if - processing doesn't start instantly. + processing does not start instantly. * Once the processing starts the status is set to `running`. * Once the data is available to download the status is set to `finished`. * Whenever an error occurs during processing, the status MUST be set to `error`. @@ -5557,11 +5556,11 @@ components: progress: type: number description: >- - Indicates the process of a running batch job in percent. + Indicates the process of a running batch job, in percent. Can also be set for a job which stopped due to an error or was canceled by the user. In this case, the value indicates - the progress at which the job stopped. The Property may not be + the progress at which the job stopped. This property may not be available for the status codes `created` and `queued`. Submitted and queued jobs only allow the value `0`, @@ -5595,10 +5594,10 @@ components: links: type: array description: |- - Links related to this batch job, e.g. a links to + Links related to this batch job such as links to invoices, log files or results. - It is RECOMMENDED to provide links with the following `rel` (relation) types: + Providing links with the following `rel` (relation) types is RECOMMENDED: 1. `monitor`: If logs are available, a link to the [logs endpoint](#tag/Batch-Jobs/operation/debug-job). 2. `result`: If batch job results are available, a link to the [results endpoint](#tag/Batch-Jobs/operation/list-results). @@ -5713,7 +5712,7 @@ components: type: string format: uri description: >- - URL at which the secondary web service is accessible. Doesn't + URL at which the secondary web service is accessible. Does not necessarily need to be located within the API. example: 'https://openeo.example/wms/wms-a3cca9' type: @@ -5729,7 +5728,7 @@ components: type: object description: >- Additional attributes of the secondary web service, e.g. - available layers for a WMS based on the bands in the + available layers for a WMS instance based on the bands in the underlying GeoTiff. example: layers: @@ -5770,14 +5769,14 @@ components: web service combined with actual values. See `GET /service_types` for supported configuration settings. For example, this could specify the required version of the service, visualization details or - any other service dependant configuration. + any other service dependent configuration. example: version: 1.3.0 service_enabled: type: boolean description: >- Describes whether a secondary web service is responding to requests - (true) or not (false). Disabled services don't produce any costs. + (true) or not (false). Disabled services do not produce any costs. service_id: type: string description: >- @@ -5910,7 +5909,7 @@ components: description: |- Updates the minimum severity level for log entries that the back-end stores for the processing requests. - The back-end doesn't need to update existing log entries. + The back-end does not need to update existing log entries. type: string enum: - error @@ -5988,7 +5987,7 @@ components: A list of parameters passed to the child process graph. The order in the array corresponds to the parameter order to - be used in clients that don't support named parameters. + be used in clients that do not support named parameters. items: $ref: '#/components/schemas/parameter' returns: @@ -6072,9 +6071,9 @@ components: $schema: description: |- The JSON Schema version. If not given in the context of openEO, - defaults to `draft-07`. + defaults to JSON Schema draft-07: `http://json-schema.org/draft-07/schema#` - You may need to add the default value for `$schema` property explicitly to the JSON Schema + The default value for `$schema` property may have to be added to the JSON Schema object before passing it to a JSON Schema validator. type: string format: uri @@ -6085,7 +6084,7 @@ components: format: uri type: description: |- - The allowed basic data type(s) for a value. + The allowed data type(s) for a value. If this property is not present, all data types are allowed. oneOf: @@ -6128,8 +6127,7 @@ components: - $ref: '#/components/schemas/json_schema' additionalProperties: description: >- - You can add any other property supported by the JSON Schema version that is given through the property `$schema`, - so either [draft-07](https://json-schema.org/draft-07/json-schema-validation.html) or any later version. + Any other property supported by the JSON Schema version that is given through the property `$schema` are allowed. Defaults to JSON Schema [draft-07](https://json-schema.org/draft-07/json-schema-validation.html), but can also be any later version of JSON Schema. json_schema_type: type: string enum: @@ -6365,7 +6363,7 @@ components: It is NOT RECOMMENDED to add stacktraces to the `message`. example: >- - Can't load the UDF file from the URL `https://openeo.example/invalid/file.txt`. + Can not load the UDF file from the URL `https://openeo.example/invalid/file.txt`. Server responded with error 404. time: type: string @@ -6516,7 +6514,7 @@ components: $ref: '#/components/schemas/links_pagination' client_error: description: |- - The request can't be fulfilled due to an error on client-side, i.e. the + The request can not be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications. @@ -6536,7 +6534,7 @@ components: $ref: '#/components/schemas/error' client_error_auth: description: |- - The request can't be fulfilled due to an error on client-side, i.e. the + The request can not be fulfilled due to an error on client-side, i.e. the request is invalid. The client SHOULD NOT repeat the request without modifications. @@ -6556,7 +6554,7 @@ components: $ref: '#/components/schemas/error' server_error: description: |- - The request can't be fulfilled due to an error at the back-end. The + The request can not be fulfilled due to an error at the back-end. The error is never the client’s fault and therefore it is reasonable for the client to retry the exact same request that triggered this response. @@ -6583,14 +6581,14 @@ components: If the parameter is not provided or empty, all elements are returned. Pagination is OPTIONAL: back-ends or clients may not support it. - Therefore it MUST be implemented in a way that clients not supporting + Therefore, it MUST be implemented in a way that clients not supporting pagination get all resources regardless. Back-ends not supporting pagination MUST return all resources. If the response is paginated, the `links` array MUST be used to communicate the links for browsing the pagination with predefined `rel` types. See the `links` array schema for supported `rel` types. - Back-end implementations can, unless specified otherwise, use all kind of pagination techniques, + Back-end implementations can, unless specified otherwise, use any kind of pagination technique, depending on what is supported best by their infrastructure: page-based, offset-based, token-based or something else. The clients SHOULD use whatever is specified in the links with the corresponding `rel` types. @@ -6602,7 +6600,7 @@ components: minimum: 1 log_offset: name: offset - description: The last identifier (property `id` of a log entry) the client has received. If provided, the back-ends only sends the entries that occurred after the specified identifier. If not provided or empty, start with the first entry. + description: The last identifier (property `id` of a log entry) the client has received. If provided, the back-end MUST only send the entries that occurred after the specified identifier. If not provided or empty, the back-end MUST start with the first entry. in: query allowEmptyValue: true example: log1234 @@ -6651,7 +6649,7 @@ components: $ref: '#/components/schemas/collection_id' examples: evi_user_defined_process: - description: A user-defined process that computes the EVI. + description: A user-defined process that computes the Enhanced Vegetation Index (EVI). value: id: evi summary: Enhanced Vegetation Index From bd5468871998e052fc35144f68b9e643814d336e Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Thu, 8 Feb 2024 22:03:44 +0100 Subject: [PATCH 13/52] Fix typo in ProcessGraphComplexity error message (#526) --- errors.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/errors.json b/errors.json index 7288ba6b..e9a60522 100644 --- a/errors.json +++ b/errors.json @@ -242,7 +242,7 @@ }, "ProcessGraphComplexity": { "description": "The process graph is too complex for synchronous processing and will likely time out. Please use a batch job instead.", - "message": "The process is too complex for for synchronous processing. Please use a batch job instead.", + "message": "The process is too complex for synchronous processing. Please use a batch job instead.", "http": 400, "tags": [ "Data Processing" From e669dbed719b35a65d6b42994dfd507238d9f70b Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Mon, 10 Jun 2024 17:40:08 +0200 Subject: [PATCH 14/52] Minor "ProcessInvalid" error typo fix (#535) --- errors.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/errors.json b/errors.json index e9a60522..41381277 100644 --- a/errors.json +++ b/errors.json @@ -200,7 +200,7 @@ ] }, "ProcessInvalid": { - "description": "The process given is invalid, which ususlly means that the process metadata is invalid.", + "description": "The given process definition is invalid, which usually means that the process metadata is invalid.", "message": "Invalid process specified.", "http": 400, "tags": [ From b70b43c6f449661e28493f47d5985d9bef46e592 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 13 Jun 2024 11:18:05 +0200 Subject: [PATCH 15/52] Fix CI --- .spectral.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.spectral.yml b/.spectral.yml index cfe29b52..13cea053 100644 --- a/.spectral.yml +++ b/.spectral.yml @@ -8,6 +8,7 @@ rules: tag-description: true oas3-parameter-description: true oas3-unused-component: false # Broken: https://github.com/stoplightio/spectral/issues/1271 + array-items: false operation-summary-formatted: description: Operation `summary` should start with upper case and not end with a dot. given: '$.paths.*[?( @property === ''get'' || @property === ''put'' || @property === ''post'' || @property === ''delete'' || @property === ''options'' || @property === ''head'' || @property === ''patch'' || @property === ''trace'' )]' From 13dc6bb4329f5779584e82e467340c93cbcd7983 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 14 Jun 2024 12:32:23 +0200 Subject: [PATCH 16/52] Document additional relation types for process metadata #531 (#536) * Document additional relation types for process metadata #531 * Fix bullet points, add canonical --- CHANGELOG.md | 1 + openapi.yaml | 14 ++++++++++++-- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fdd0e0eb..7622bc24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `PATCH /services/{service_id}` and `PATCH /jobs/{job_id}`: Explicitly allow updating back-end specific properties (as in `POST`) - `GET /services/{service_id}` and `GET /jobs/{job_id}`: Explicitly allow listing back-end specific properties (as provided in `POST`) - Clarified for log levels which default values apply +- Clarified how the relation types `license`, `version-history` and `author` can be used to enrich the process metadata. [#531](https://github.com/Open-EO/openeo-api/issues/531) ## [1.2.0] - 2021-05-25 diff --git a/openapi.yaml b/openapi.yaml index bf98aec3..a97d448f 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -5262,11 +5262,21 @@ components: (link to older version) and `successor-version` (link to newer version) can also be used to show the relation between versions. - 2. `example`: Links to examples of other processes that use this process. + 2. `version-history`: A link to a changelog and/or a list of versions of the process + (see also the relation types `latest-version` etc.). - 3. `cite-as`: For all DOIs associated with the process, the respective DOI + 3. `example`: Links to examples of other processes that use this process. + + 4. `cite-as`: For all DOIs associated with the process, the respective DOI links SHOULD be added. + 5. `license`: Links to applicable license(s). The link titles should reflect the license names. + + 6. `author`: Links to authors of the process. The `href` can use the `mailto:` protocol to + link to an email address. The link titles should reflect the author names and affiliations. + + 7. `canonical`: Points to a publicly accessible and more long-lived URL. + For additional relation types see also the lists of [common relation types in openEO](#section/API-Principles/Web-Linking). items: From caef6e4f90c35657a0845a477c7d585909f4d898 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 1 Jul 2024 15:06:46 +0200 Subject: [PATCH 17/52] Add Remote UDP extension #515 (#538) Co-authored-by: Stefaan Lippens --- CHANGELOG.md | 5 +++ README.md | 1 + extensions/remote-udp/README.md | 69 +++++++++++++++++++++++++++++++++ 3 files changed, 75 insertions(+) create mode 100644 extensions/remote-udp/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7622bc24..baf9432a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased / Draft +### Added + +- **New extensions:** + - [Remote UDP Extension](./extensions/remote-udp/README.md) + ### Fixed - `GET /file_formats`: Base paramater on top of normal JSON Schema, not Process JSON Schema diff --git a/README.md b/README.md index aef37924..2a9ac639 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ See also the [changelog](CHANGELOG.md) and the [milestones](https://github.com/O | ---------------------------------------------- | ------- | ------------ | ----------- | | [Commercial Data](extensions/commercial-data/) | 0.1.0 | experimental | Provides an interface for discovering, ordering and using commercial data. | | [Federation](extensions/federation/) | 0.1.0 | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. | +| [Remote UDP](extensions/remote-udp/) | 0.1.0 | experimental | Load user-defined processes that are hosted externally through the process namespace into process graphs. | ## Repository diff --git a/extensions/remote-udp/README.md b/extensions/remote-udp/README.md new file mode 100644 index 00000000..812568bc --- /dev/null +++ b/extensions/remote-udp/README.md @@ -0,0 +1,69 @@ +# Remote UDP Extension + +The openEO API is a specification for interoperable cloud-based processing of large Earth observation datasets. + +This extension enables user to load user-defined processes that are hosted external to the openEO API (e.g., GitHub or cloud storage) through the process namespace into process graphs. + +- Version: **0.1.0** +- Stability: **experimental** +- Conformance class: `https://api.openeo.org/extensions/remote-udp/0.1.0` + +## Justification + +The openEO API defines the `namespace` property in a process node of a process graph as follows: +> The following options are predefined by the openEO API, but additional namespaces may be introduced by back-ends or in a future version of the API. +> * `null` [...] +> * `backend` [...] +> * `user` [...] + +This makes it possible for this extension to add additional allowed values to the `namespace` property. + +## Specification + +This extension extends the `namespace` property of process graph nodes so that it accepts **absolute** URL with the protocols `https` (**recommended**) and `http` (discouraged). The URLs specified MUST return one of the following two options: + +1. A single process, compatible\* to the endpoint `GET /process_graphs/{process_graph_id}`. + In this case, the `id` property of the process graph node MUST be equal to the `id` of the process, + otherwise a `ProcessNamespaceInvalid` error is thrown +2. A list of processes, compatible\* to the endpoint `GET /process_graphs`. + In this case, the `id` property of the process graph node is used to identify the process from the list. + If not found a `ProcessNamespaceInvalid` error is thrown + +\* Compatible means in this context that the requests and responses must comply to the openEO API specification with the following exceptions: + +- User credentials / tokens that are obtained through the openEO API MUST NOT not be sent to URIs that are external to the openEO API. + The requirement to provide an `Authorization` header for the respective endpoints doesn't apply. +- For a list of processes, the full process description MUST be provided for the process with the given ID within the first request. + This means that the recommendation to omit large roperties such as `process_graph` doesn't apply. + It also requires that the requester doesn't need to paginate through additional pages to find the process with the given ID. + Ideally, the list of processes is not paginated as otherwise the process with the given ID may move to other pages over time. + +### Client Considerations + +If a client is conncected to a specific backend, the client MUST only offer this functionality to users if the conformance class of this extension is listed in the `conformsTo` property of the `GET /` endpoint. + +The protocol `http` is discouraged for URLs as web-based clients may not be able to retrieve HTTP URLs from a HTTPS context. +For the same reason it is also RECOMMENDED to enable CORS for all URLs. + +### Error Handling + +The following error SHOULD be reported if the namespace can't be resolved: + +- Code: `ProcessNamespaceInvalid` +- Message: `The value passed for namespace '{namespace}' in process '{process}' is invalid: {reason}` +- HTTP Status Code: 400 + +## Example + +An exemplary process graph node: + +```json +{ + "process_id": "echo", + "namespace": "https://openeo.example/processes/echo", + "arguments": { + "message": "Hello World" + }, + "result": true +} +``` From 777fa7c3f55b0f2e36aa7b0be3ca4fa18662f74d Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 8 Jul 2024 20:41:43 +0200 Subject: [PATCH 18/52] Rename Remote UDP extension #540 --- CHANGELOG.md | 6 +++--- README.md | 12 ++++++------ .../README.md | 7 ++++--- 3 files changed, 13 insertions(+), 12 deletions(-) rename extensions/{remote-udp => remote-process-definition}/README.md (91%) diff --git a/CHANGELOG.md b/CHANGELOG.md index baf9432a..9a395e96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - **New extensions:** - - [Remote UDP Extension](./extensions/remote-udp/README.md) + - [Remote Process Definition Extension](./extensions/remote-process-definition/README.md) ### Fixed @@ -24,8 +24,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - **New extensions:** - - [Commercial Data Extension](./extensions/commercial-data/README.md) - - [Federation Extension](./extensions/federation/README.md) + - [Commercial Data Extension](./extensions/commercial-data/README.md) + - [Federation Extension](./extensions/federation/README.md) - `GET /`: New Relation types: [#404](https://github.com/Open-EO/openeo-api/issues/404) - `create-form` to link to the registration page - `recovery-form` to link to the credentials recovery page. diff --git a/README.md b/README.md index 2a9ac639..9917cdfa 100644 --- a/README.md +++ b/README.md @@ -29,11 +29,11 @@ See also the [changelog](CHANGELOG.md) and the [milestones](https://github.com/O ## Extensions -| Name | Version | Stability | Description | -| ---------------------------------------------- | ------- | ------------ | ----------- | -| [Commercial Data](extensions/commercial-data/) | 0.1.0 | experimental | Provides an interface for discovering, ordering and using commercial data. | -| [Federation](extensions/federation/) | 0.1.0 | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. | -| [Remote UDP](extensions/remote-udp/) | 0.1.0 | experimental | Load user-defined processes that are hosted externally through the process namespace into process graphs. | +| Name | Version | Stability | Description | +| ------------------------------------------------------------------ | ------- | ------------ | ----------- | +| [Commercial Data](extensions/commercial-data/) | 0.1.0 | experimental | Provides an interface for discovering, ordering and using commercial data. | +| [Federation](extensions/federation/) | 0.1.0 | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. | +| [Remote Process Definition](extensions/remote-process-definition/) | 0.1.0 | experimental | Load user-defined processes that are hosted externally through the process namespace into process graphs. | ## Repository @@ -44,7 +44,7 @@ This repository contains a set of files formally describing the openEO API, each * The [assets](assets/) folder contains some useful additional files such as examples or schemas. All of these are non-binding additions. The source of truth are the top-level specification files. * The [extensions](extensions/) folder contains extensions to the openEO API. -# Development +## Development The `draft` branch is the latest version and is the one to create Pull Requests against. diff --git a/extensions/remote-udp/README.md b/extensions/remote-process-definition/README.md similarity index 91% rename from extensions/remote-udp/README.md rename to extensions/remote-process-definition/README.md index 812568bc..d120d48b 100644 --- a/extensions/remote-udp/README.md +++ b/extensions/remote-process-definition/README.md @@ -1,4 +1,4 @@ -# Remote UDP Extension +# Remote Process Definition Extension The openEO API is a specification for interoperable cloud-based processing of large Earth observation datasets. @@ -6,12 +6,13 @@ This extension enables user to load user-defined processes that are hosted exter - Version: **0.1.0** - Stability: **experimental** -- Conformance class: `https://api.openeo.org/extensions/remote-udp/0.1.0` +- Conformance class: `https://api.openeo.org/extensions/remote-process-definition/0.1.0` ## Justification The openEO API defines the `namespace` property in a process node of a process graph as follows: -> The following options are predefined by the openEO API, but additional namespaces may be introduced by back-ends or in a future version of the API. + +> The following options are predefined by the openEO API, but additional namespaces may be introduced by back-ends or in a future version of the API. > * `null` [...] > * `backend` [...] > * `user` [...] From 23d47fb9bce61c48473bb641f024ebbac37b93bd Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 28 Aug 2024 14:48:03 +0200 Subject: [PATCH 19/52] More possibilities for federation extension --- extensions/federation/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/extensions/federation/README.md b/extensions/federation/README.md index 9343f0ab..2bcb9f7b 100644 --- a/extensions/federation/README.md +++ b/extensions/federation/README.md @@ -115,9 +115,11 @@ Applies to: - `GET /processes` - `GET /file_formats` - `GET /process_graphs` +- `GET /files` - `GET /jobs` - `GET /jobs/{job_id}` - `GET /jobs/{job_id}/results` +- `GET /jobs/{job_id}/logs` - `GET /services` The following endpoints define the resources (UDF runtimes / service types) at the top level of their response as key-value pairs. @@ -160,6 +162,7 @@ Every discoverable resource that is defined as an object and allows to contain a - `GET /collections/{id}` - `GET /processes` (per process, per parameter) - `GET /file_formats` (per file format) +- `GET /service_types` (per service) - `GET /udf_runtimes` (per UDF runtime, per version) - `POST /validation` (the back-ends that can run the process) - `GET /process_graphs/{id}` From 5feccf793a88f6c13b39c4f0ba4cca1601050282 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Tue, 3 Sep 2024 11:43:15 +0200 Subject: [PATCH 20/52] Issue #527 Generalize ProcessGraphComplexity error message/description (#528) --- errors.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/errors.json b/errors.json index 41381277..7e23b496 100644 --- a/errors.json +++ b/errors.json @@ -241,8 +241,8 @@ ] }, "ProcessGraphComplexity": { - "description": "The process graph is too complex for synchronous processing and will likely time out. Please use a batch job instead.", - "message": "The process is too complex for synchronous processing. Please use a batch job instead.", + "description": "The process graph is computationally too heavy for synchronous processing and will likely time out. Please use a batch job instead.", + "message": "The process graph is too heavy for synchronous processing. Please use a batch job instead.", "http": 400, "tags": [ "Data Processing" From 7eccf0bdd876bbb9ddda88783890242cd63389a1 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 9 Sep 2024 13:39:25 +0200 Subject: [PATCH 21/52] Add workspace_providers endpoint, add intent/type to other endpoints --- extensions/workspaces/openapi.yaml | 164 ++++++++++++++++++++++++----- 1 file changed, 139 insertions(+), 25 deletions(-) diff --git a/extensions/workspaces/openapi.yaml b/extensions/workspaces/openapi.yaml index 9bfab4b3..f7eb7bc2 100644 --- a/extensions/workspaces/openapi.yaml +++ b/extensions/workspaces/openapi.yaml @@ -38,6 +38,93 @@ servers: the version number of the API. Use the version number returned from `GET /` instead. paths: + /workspace_providers: + get: + summary: Supported workspace providers + operationId: list-workspace-providers + description: |- + Lists supported workspace providers such as Amazon S3, Google Cloud Storage or Azure Blob Storage. + The response is an object of all available workspace providers with their supported parameters, + e.g. credentials for registering an existing workspace. + + The parameters for the workspace provider MUST be defined upon creation + of a workspace and the workspace will be set up accordingly. + + Workspace provider names MUST be accepted in a *case insensitive* manner throughout the API. + tags: + - Workspaces + security: + - {} + - Bearer: [] + responses: + '200': + description: >- + An object with a map containing all workspace provider names as keys and an + object that defines supported parameters, e.g. credentials. + content: + application/json: + schema: + title: Workspace Providers + type: object + properties: + providers: + type: object + description: Map of supported workspace providers + additionalProperties: + x-additionalPropertiesName: Provider Name + title: Provider + type: object + required: + - parameters + properties: + title: + $ref: '../../openapi.yaml#/components/schemas/object_title' + description: + $ref: '../../openapi.yaml#/components/schemas/description' + deprecated: + $ref: '../../openapi.yaml#/components/schemas/deprecated' + experimental: + $ref: '../../openapi.yaml#/components/schemas/experimental' + intents: + type: array + minItems: 1 + items: + type: string + enum: + - create + - register + parameters: + title: Provider specific parameters + description: Map of supported parameters made available to the creator of the workspace. + type: object + additionalProperties: + $ref: '../../openapi.yaml#/components/schemas/resource_parameter' + links: + description: |- + Links related to this workspace provider, e.g. more information about the parameters. + + For relation types see the lists of + [common relation types in openEO](#section/API-Principles/Web-Linking). + type: array + items: + $ref: '../../openapi.yaml#/components/schemas/link' + example: + providers: + S3: + title: Amazon S3 + description: >- + Amazon S3 is a cloud storage service provided by Amazon Web Services. + intents: + - create + - register + parameters: + username: + title: Username + type: string + password: + title: Password + type: string + links: [] /workspaces: get: summary: List all workspaces @@ -104,26 +191,14 @@ paths: quota: $ref: '../../openapi.yaml#/components/schemas/max_storage_quota' oneOf: - - title: Create workspace - properties: - intent: - enum: - - create - example: create - - title: Register existing workspace - required: - - url - - credentials - properties: - intent: - enum: - - register - example: register - url: - $ref: '#/components/schemas/workspace_url' - credentials: - $ref: '#/components/schemas/workspace_credentials' - required: true + - $ref: '#/components/schemas/create_workspace' + - $ref: '#/components/schemas/register_workspace' + discriminator: + propertyName: intent + mapping: + create: '#/components/schemas/create_workspace' + register: '#/components/schemas/register_workspace' + required: true responses: '201': description: The workspace creation has been queued successfully. @@ -244,6 +319,7 @@ components: required: - id - status + - type type: object properties: id: @@ -252,9 +328,15 @@ components: $ref: '#/components/schemas/workspace_title' description: $ref: '#/components/schemas/workspace_description' + type: + type: string + description: >- + The workspace provider name as defined in `GET /workspace_providers`. + example: S3 status: type: string description: The status of the workspace. + example: ready details: type: string description: >- @@ -280,8 +362,6 @@ components: example: ready url: $ref: '#/components/schemas/workspace_url' - credentials: - $ref: '#/components/schemas/workspace_credentials' properties: $ref: '#/components/schemas/workspace_properties' free: @@ -291,13 +371,13 @@ components: format: uri description: The URL of the actual workspace, e.g. a bucket URL. example: 'https://my-bucket.s3.eu-west-3.amazonaws.com' - workspace_credentials: + workspace_parameters: type: object description: >- - Credentials to access the workspace as required by the workspace provider. + Additional parameters to register the workspace as defined in `GET /workspace_types`. The structure is not specified by the API. additionalProperties: - type: string + description: Any type example: username: john_doe password: secret123 @@ -311,6 +391,40 @@ components: example: region: eu-west-3 storage_class: standard + create_workspace: + title: Create workspace + properties: + intent: + enum: + - create + example: create + type: + type: string + nullable: true + description: >- + The workspace provider name as defined in `GET /workspace_providers`. + If not provided or `null`, the back-end chooses a default provider. + default: null + parameters: + $ref: '#/components/schemas/workspace_parameters' + register_workspace: + required: + - type + - url + - credentials + properties: + intent: + enum: + - register + example: register + type: + type: string + description: >- + The workspace provider name as defined in `GET /workspace_providers`. + url: + $ref: '#/components/schemas/workspace_url' + parameters: + $ref: '#/components/schemas/workspace_parameters' securitySchemes: Bearer: $ref: '../../openapi.yaml#/components/securitySchemes/Bearer' From 162952e62012a667172bcf9ec222712041f6a828 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 21 Oct 2024 15:06:28 +0200 Subject: [PATCH 22/52] Fix field name in OpenAPI document for Workspace extension --- extensions/workspaces/openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/workspaces/openapi.yaml b/extensions/workspaces/openapi.yaml index f7eb7bc2..a8e64da3 100644 --- a/extensions/workspaces/openapi.yaml +++ b/extensions/workspaces/openapi.yaml @@ -411,7 +411,7 @@ components: required: - type - url - - credentials + - parameters properties: intent: enum: From 16f4c27280d2a7aa62c1bc15b1f909222c062b40 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 20 Nov 2024 07:46:47 -0600 Subject: [PATCH 23/52] Add openEO processes version #517 (#549) * Add openEO processes version #517 * Update openapi.yaml * Update openapi.yaml Co-authored-by: Stefaan Lippens * Update openapi.yaml --------- Co-authored-by: Stefaan Lippens --- CHANGELOG.md | 1 + openapi.yaml | 13 ++++++++++++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a395e96..c2a179ec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **New extensions:** - [Remote Process Definition Extension](./extensions/remote-process-definition/README.md) +- Added `version` property to `GET /processes` [#517](https://github.com/Open-EO/openeo-api/issues/517) ### Fixed diff --git a/openapi.yaml b/openapi.yaml index bcf8266d..3237fafb 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -615,7 +615,7 @@ paths: api_version: type: string description: >- - Version number of the openEO specification this back-end + Version number of the openEO API specification this back-end implements. enum: - 1.2.0 @@ -1660,6 +1660,17 @@ paths: - processes - links properties: + version: + type: string + nullable: true + description: >- + Version number of the openEO process specification this back-end + targets. + If not provided or `null`, the version is either unknown or multiple versions are implemented. + Clients must be able to handle multiple process specification versions at the same time. + + This is **not** the openEO API specification version. + example: 1.2.0 processes: type: array items: From 8393536b6d894d0f79a4c291026c7dde52d28cc8 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Sun, 1 Dec 2024 21:30:35 +0100 Subject: [PATCH 24/52] backend -> back-end --- extensions/commercial-data/README.md | 15 ++++++++------- extensions/commercial-data/openapi.yaml | 6 +++--- extensions/federation/README.md | 4 ++-- extensions/remote-process-definition/README.md | 2 +- extensions/workspaces/openapi.yaml | 2 +- openapi.yaml | 8 ++++---- 6 files changed, 19 insertions(+), 18 deletions(-) diff --git a/extensions/commercial-data/README.md b/extensions/commercial-data/README.md index 6e6ae84a..ed2b8782 100644 --- a/extensions/commercial-data/README.md +++ b/extensions/commercial-data/README.md @@ -12,7 +12,7 @@ Extensions can not change or break existing behavior of the openEO API. ## Overview of the workflow -All the available datasets provided by a backend are listed on the `GET /collections` endpoint. The collections are normally freely accessible. This extension adds capabilities for providing collections that are not free of charge and require purchasing data products that can thereupon be used in processing. Commercial data collections usually allow purchasing small subsets of the data (products), for example, a single observation of an area. +All the available datasets provided by a back-end are listed on the `GET /collections` endpoint. The collections are normally freely accessible. This extension adds capabilities for providing collections that are not free of charge and require purchasing data products that can thereupon be used in processing. Commercial data collections usually allow purchasing small subsets of the data (products), for example, a single observation of an area. Therefore, the client must have an ability to search the available products that match their desired criteria and inspect their metadata to decide whether the products should be purchased. @@ -22,7 +22,7 @@ When the order is completed, the data is ingested in a collection and its ID is ### Collection discovery -A backend should add general information about a commercial data collection to the `/collections` and `/collections/{collection_id}` endpoints, the same as with freely available collections. Only the metadata about the entire dataset needs to be provided, not about the specific data products that a user has already purchased. +A back-end should add general information about a commercial data collection to the `/collections` and `/collections/{collection_id}` endpoints, the same as with freely available collections. Only the metadata about the entire dataset needs to be provided, not about the specific data products that a user has already purchased. Commercial data collections are distinguished from freely available collections by including `"order:status": "orderable"` as specified in the [STAC Order extension](https://github.com/stac-extensions/order/tree/v1.0.0). @@ -82,7 +82,7 @@ Commercial data collections must also include human-readable pricing information ### Filtering parameters discovery -Searching for products can support refining the search by filtering with general or collection-specific attributes. Backends should implement a top level `/queryables` endpoint for attributes available for all collections, and collection-specific attributes should be provided at `/collections/{collection_id}/queryables` according to [OGC Queryables specification](https://portal.ogc.org/files/96288#filter-queryables) and [STAC Filter extension](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/fragments/filter). +Searching for products can support refining the search by filtering with general or collection-specific attributes. Back-ends should implement a top level `/queryables` endpoint for attributes available for all collections, and collection-specific attributes should be provided at `/collections/{collection_id}/queryables` according to [OGC Queryables specification](https://portal.ogc.org/files/96288#filter-queryables) and [STAC Filter extension](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/fragments/filter). #### Example @@ -125,7 +125,7 @@ Example response from `GET /collections/PLEIADES/queryables`: ### Searching available products -Backends should implement the top-level `GET /search` endpoint as specified in the [STAC Item Search API specification](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/item-search). This should include the [Filter Extension](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/fragments/filter), which enables filtering the available products by attributes specified in `GET /queryables` and `GET /collections/{collection-id}/queryables`. +Back-ends should implement the top-level `GET /search` endpoint as specified in the [STAC Item Search API specification](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/item-search). This should include the [Filter Extension](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-rc.1/fragments/filter), which enables filtering the available products by attributes specified in `GET /queryables` and `GET /collections/{collection-id}/queryables`. The endpoint returns a list of [STAC Items](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md) that match the criteria. The products should be aligned with the STAC specification, utilising the existing [STAC extensions](https://github.com/radiantearth/stac-spec/blob/v1.0.0/extensions/README.md) as much as possible, and trying avoiding custom attributes, if a generally accepted definition does not exist. #### Example @@ -155,7 +155,7 @@ Example request payload to `GET /search` for `PLEIADES` products from "Living Li ### Ordering products -Backends must implement the following endpoints: +Back-ends must implement the following endpoints: - `GET /orders`: Get a list of all created orders - `POST /orders`: Create an order @@ -163,13 +163,14 @@ Backends must implement the following endpoints: - `POST /orders/{order_id}`: Confirm a created order Optionally, they can also implement: + - `DELETE /orders/{order_id}`: Delete an order See the [OpenAPI document](openapi.yaml) for details. ### Product metadata -The backend can provide full product metadata as STAC Items following [STAC API Features specification](https://github.com/radiantearth/stac-api-spec/tree/main/ogcapi-features). This requires implementing two additional endpoints, `/collections/{collection_id}/items` and `/collections/{collection_id}/items/{item_id}`. +The back-end can provide full product metadata as STAC Items following [STAC API Features specification](https://github.com/radiantearth/stac-api-spec/tree/main/ogcapi-features). This requires implementing two additional endpoints, `/collections/{collection_id}/items` and `/collections/{collection_id}/items/{item_id}`. `/collections/{collection_id}/items/{item_id}` may return an error if the data has not been ingested yet. @@ -177,7 +178,7 @@ Items should contain links to the respective orders that made them available usi ### Payment -Payment should be done in the currency used by the backend, listed at `GET /` under `billing`. When an order is created, the backend should return the full final cost of the order. +Payment should be done in the currency used by the back-end, listed at `GET /` under `billing`. When an order is created, the back-end should return the full final cost of the order. ### Example usage with Python client diff --git a/extensions/commercial-data/openapi.yaml b/extensions/commercial-data/openapi.yaml index 00506f60..bab5637d 100644 --- a/extensions/commercial-data/openapi.yaml +++ b/extensions/commercial-data/openapi.yaml @@ -87,7 +87,7 @@ paths: The order can contain additional parameters that specify how the items should be delivered. For example, it might be possible to set the projection, resampling method, bit depth etc. of the delivered data. - Backends SHOULD expose the available ordering parameters in `GET /collections/{collection_id}` in the `order_parameters` field, following the `process_parameters` schema of [`GET /service_types`](https://openeo.org/documentation/1.0/developers/api/reference.html#tag/Secondary-Services/operation/list-service-types). + Back-ends SHOULD expose the available ordering parameters in `GET /collections/{collection_id}` in the `order_parameters` field, following the `process_parameters` schema of [`GET /service_types`](https://openeo.org/documentation/1.0/developers/api/reference.html#tag/Secondary-Services/operation/list-service-types). Returns `Location` and `OpenEO-Identifier` header with the link to the detailed information about the order. tags: @@ -148,7 +148,7 @@ paths: description: |- Get full metadata of the order. - Backends can optionally link to the spatial and temporal extent information and other metadata about the items using the relation type `item`, preferrably by implementing and linking to `GET /collections/{collection_id}/items/{item_id}`. + Back-ends can optionally link to the spatial and temporal extent information and other metadata about the items using the relation type `item`, preferrably by implementing and linking to `GET /collections/{collection_id}/items/{item_id}`. tags: - Orders security: @@ -176,7 +176,7 @@ paths: When an order is created through `POST /order`, the data isn't yet ordered from the commercial data provider. The client MUST explicitly confirm the order whereupon the order is executed, the costs are deducted from the client's account and the data is ingested in the target collection. - The target collection is the collection through which the ordered data is made available. The source and the target collection can be the same or different, it's up to the backend if the ordered data id ingested into a new target collection or the existing source collection. Additionally, if the backend creates new target collections, it can provide access to the union of all purchased products through the source collection. + The target collection is the collection through which the ordered data is made available. The source and the target collection can be the same or different, it's up to the back-end if the ordered data id ingested into a new target collection or the existing source collection. Additionally, if the back-end creates new target collections, it can provide access to the union of all purchased products through the source collection. This endpoint only has an effect if `order:status` is `orderable`. diff --git a/extensions/federation/README.md b/extensions/federation/README.md index 2bcb9f7b..4e846125 100644 --- a/extensions/federation/README.md +++ b/extensions/federation/README.md @@ -11,7 +11,7 @@ This is an extension for federation aspects, i.e. where multiple back-ends are e **Note:** This document only documents the additions to the specification. Extensions can not change or break existing behavior of the openEO API. -## Backend details +## Back-end details A new required field `federation` is added to `GET /` to enable federation. @@ -157,7 +157,7 @@ schema: ## Resources supported only by a subset of back-ends -Every discoverable resource that is defined as an object and allows to contain additional properties, can list the backends that support or host the exposed resource/functionality. Examples of where this could apply to (**not** comprehensive): +Every discoverable resource that is defined as an object and allows to contain additional properties, can list the back-ends that support or host the exposed resource/functionality. Examples of where this could apply to (**not** comprehensive): - `GET /collections/{id}` - `GET /processes` (per process, per parameter) diff --git a/extensions/remote-process-definition/README.md b/extensions/remote-process-definition/README.md index d120d48b..7ee7f76e 100644 --- a/extensions/remote-process-definition/README.md +++ b/extensions/remote-process-definition/README.md @@ -41,7 +41,7 @@ This extension extends the `namespace` property of process graph nodes so that i ### Client Considerations -If a client is conncected to a specific backend, the client MUST only offer this functionality to users if the conformance class of this extension is listed in the `conformsTo` property of the `GET /` endpoint. +If a client is conncected to a specific back-end, the client MUST only offer this functionality to users if the conformance class of this extension is listed in the `conformsTo` property of the `GET /` endpoint. The protocol `http` is discouraged for URLs as web-based clients may not be able to retrieve HTTP URLs from a HTTPS context. For the same reason it is also RECOMMENDED to enable CORS for all URLs. diff --git a/extensions/workspaces/openapi.yaml b/extensions/workspaces/openapi.yaml index a8e64da3..e0115195 100644 --- a/extensions/workspaces/openapi.yaml +++ b/extensions/workspaces/openapi.yaml @@ -250,7 +250,7 @@ paths: summary: Delete Workspace operationId: delete-workspace description: |- - Removes the workspace from the backend. + Removes the workspace from the back-end. tags: - Workspaces security: diff --git a/openapi.yaml b/openapi.yaml index 3237fafb..7db07d80 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -25,7 +25,7 @@ info: Public API implementations MUST be available via HTTPS only. - Endpoints are made use meaningful HTTP verbs (e.g. GET, POST, PUT, PATCH, DELETE) whenever technically possible. If there is a need to transfer big chunks of data for a GET requests to the back-end, POST requests MAY be used as a replacement as they support to send data via request body. Unless otherwise stated, PATCH requests are only defined to work on direct (first-level) children of the full JSON object. Therefore, changing a property on a deeper level of the full JSON object always requires sending the whole JSON object defined by the first-level property. + Endpoints are made use meaningful HTTP verbs (e.g. GET, POST, PUT, PATCH, DELETE) whenever technically possible. If there is a need to transfer big chunks of data for a GET requests to the back-end, POST requests MAY be used as a replacement as they support to send data via request body. Unless otherwise stated, PATCH requests are only defined to work on direct (first level) children of the full JSON object. Therefore, changing a property on a deeper level of the full JSON object always requires sending the whole JSON object defined by the first-level property. Naming rules of the API endpoints follow the REST principles. Therefore, endpoints are centered around resources. Resource identifiers MUST be named with a noun in plural form except for single actions that can not be modelled with the regular HTTP verbs. Single actions MUST be single endpoints with a single HTTP verb (POST is RECOMMENDED) and no other endpoints beneath it. @@ -1935,7 +1935,7 @@ paths: id: type: string description: >- - A per-backend **unique** identifier for the OpenID Connect Provider to + A per-back-end **unique** identifier for the OpenID Connect Provider to be as prefix for the Bearer token. pattern: '[\d\w]{1,20}' issuer: @@ -5651,7 +5651,7 @@ components: job_id: type: string description: >- - Per-backend unique identifier of the batch job, generated by the + Per-back-end unique identifier of the batch job, generated by the back-end during creation. MUST match the specified pattern. pattern: '^[\w\-\.~]+$' example: a3cca2b2aa1e3b5b @@ -5805,7 +5805,7 @@ components: service_id: type: string description: >- - A per-backend unique identifier of the secondary web service, generated + A per-back-end unique identifier of the secondary web service, generated by the back-end during creation. MUST match the specified pattern. pattern: '^[\w\-\.~]+$' example: wms-a3cca9 From 29318ff223c44d7a00b28538a83678a82a4afc2e Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Sun, 1 Dec 2024 21:55:33 +0100 Subject: [PATCH 25/52] Update CI --- .github/workflows/docs.yml | 10 +++++----- .github/workflows/tests.yml | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 1f305979..c60a86bd 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,11 +11,11 @@ jobs: runs-on: ubuntu-latest steps: - name: Inject env variables - uses: rlespinasse/github-slug-action@v3.x - - uses: actions/setup-node@v3 + uses: rlespinasse/github-slug-action@v5 + - uses: actions/setup-node@v4 with: node-version: 'lts/*' - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - run: | npm install npm run build @@ -33,7 +33,7 @@ jobs: cp errors.json gh-pages/errors.json cp -rv assets/. gh-pages/assets/ - name: deploy to root (master) - uses: peaceiris/actions-gh-pages@v3 + uses: peaceiris/actions-gh-pages@v4 if: ${{ env.GITHUB_REF_SLUG == 'master' }} with: github_token: ${{ secrets.GITHUB_TOKEN }} @@ -42,7 +42,7 @@ jobs: user_name: 'openEO CI' user_email: openeo.ci@uni-muenster.de - name: deploy to ${{ env.GITHUB_REF_SLUG }} - uses: peaceiris/actions-gh-pages@v3 + uses: peaceiris/actions-gh-pages@v4 if: ${{ env.GITHUB_REF_SLUG != 'master' }} with: github_token: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 52364fe1..905d920b 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -4,10 +4,10 @@ jobs: deploy: runs-on: ubuntu-latest steps: - - uses: actions/setup-node@v3 + - uses: actions/setup-node@v4 with: node-version: 'lts/*' - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Run core tests run: | npm install From c4da5e1fe7ef3ddefc8df9baee2cc067b4163cba Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Sun, 1 Dec 2024 22:38:17 +0100 Subject: [PATCH 26/52] Consortium -> Project Steering Committee --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 7db07d80..14a65bbf 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -473,7 +473,7 @@ info: Please be aware that the result node (`result` set to `true`) is not necessarily the last node that is executed. The author of the process graph may choose to set a non-end node to the result node! contact: - name: openEO Consortium + name: openEO Project Steering Committee url: 'https://openeo.org' email: openeo.psc@uni-muenster.de license: From 5a8ce51e0636a986e4bc0d335ad086df089f43b4 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Sun, 1 Dec 2024 22:41:43 +0100 Subject: [PATCH 27/52] Fix CORS link --- openapi.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi.yaml b/openapi.yaml index 14a65bbf..68cf74d7 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -161,7 +161,7 @@ info: Source: [https://en.wikipedia.org/wiki/Cross-origin_resource_sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) - openEO-based back-ends are usually hosted on a different domain / host than the client that is requesting data from the back-end. Therefore, most requests to the back-end are blocked by all modern browsers. This leads to the problem that the JavaScript library and any browser-based application can not access back-ends. Therefore, all back-end providers SHOULD support CORS to enable browser-based applications to access back-ends. [CORS is a recommendation of the W3C organization](https://www.w3.org/TR/cors/). The following chapters explain how back-end providers can implement CORS support. + openEO-based back-ends are usually hosted on a different domain / host than the client that is requesting data from the back-end. Therefore, most requests to the back-end are blocked by all modern browsers. This leads to the problem that the JavaScript library and any browser-based application can not access back-ends. Therefore, all back-end providers SHOULD support CORS to enable browser-based applications to access back-ends. [CORS is a recommendation of the W3C organization](https://www.w3.org/TR/2020/SPSD-cors-20200602/). The following chapters explain how back-end providers can implement CORS support. **Tip**: Most servers can send the required headers and the responses to the OPTIONS requests automatically for all endpoints. Otherwise, a proxy server may be used to add the headers and OPTIONS responses. From 7833f9376e47818fcc6f0512f183ac9505d10d38 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 11 Dec 2024 14:44:20 +0100 Subject: [PATCH 28/52] Review comments by Scott Simmons --- openapi.yaml | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 68cf74d7..52313981 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -61,7 +61,7 @@ info: If a URL should be publicly available to everyone, it can simply a user-specific URL, e.g. `https://openeo.example/processes/john_doe/ndvi`. For resources that should only be accessible to a certain group of user, a signed URL could be given, e.g. `https://openeo.example/processes/81zjh1tc2pt52gbx/ndvi`. - Generally, it is RECOMMENDED adding descriptive titles (propertty `title`) and media type information (propertty `type`) for a better user experience. + Generally, it is RECOMMENDED adding descriptive titles (property `title`) and media type information (property `type`) for a better user experience. ## Error Handling @@ -137,7 +137,7 @@ info: ## Temporal data - Date, time, time intervals, and durations are formatted based on ISO 8601 or its profile [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) whenever there is an appropriate encoding available in the standard. All temporal data are specified based on the Gregorian calendar. + Date, time, time intervals, and durations are formatted based on [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) or its profile [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) whenever there is an appropriate encoding available in the standard. All temporal data are specified based on the Gregorian calendar. # Authentication @@ -437,7 +437,7 @@ info: ### Full example for an EVI computation - Deriving minimum EVI (Enhanced Vegetation Index) measurements over pixel time series of Sentinel 2 imagery. The main process graph in blue, child process graphs in yellow: + Deriving minimum EVI (Enhanced Vegetation Index) measurements over pixel time series of Sentinel-2 imagery. The main process graph in blue, child process graphs in yellow: ![Graph with processing instructions](assets/pg-evi-example.png) @@ -451,7 +451,7 @@ info: 2. A more dynamic way of processing and accessing data is to create a **secondary web service**. They allow web-based access using different protocols such as [OGC WMS](http://www.opengeospatial.org/standards/wms), [OGC WCS](http://www.opengeospatial.org/standards/wcs), [OGC API - Features](https://www.ogc.org/standards/ogcapi-features) or [XYZ tiles](https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames). Some protocols such as the OGC WMS or XYZ tiles allow users to change the viewing extent or level of detail (zoom level). Therefore, computations often run *on demand* so that the requested data is calculated during the request. Back-ends should make sure to cache processed data to avoid additional/high costs and reduce waiting times for the user. - 3. Processes can also be executed **on-demand** (i.e. synchronously). Results are delivered with the request itself and no job is created. Only lightweight computations, for example previews, should be executed using this approach as timeouts are to be expected for [long-polling HTTP requests](https://www.pubnub.com/blog/2014-12-01-http-long-polling/). + 3. Processes can also be executed **on-demand** (i.e. synchronously). Results are delivered with the request itself and no job is created. Only lightweight computations, for example previews, should be executed using this approach as timeouts are to be expected for [long-polling HTTP requests](https://www.pubnub.com/guides/long-polling/). ### Validation @@ -615,7 +615,7 @@ paths: api_version: type: string description: >- - Version number of the openEO API specification this back-end + Version number of the openEO API specification the back-end implements. enum: - 1.2.0 @@ -947,7 +947,7 @@ paths: path. Make sure to correctly handle leading/trailing slashes. 3. Send a request to the new URI. A. On success: Detect the most suitable API instance/version (see above) - and read the [capabilites](#tag/Capabilities/operation/capabilities) + and read the [capabilities](#tag/Capabilities/operation/capabilities) from there. B. On failure: Directly try to read the capabilities from the original URI given by the user. @@ -1191,7 +1191,7 @@ paths: all OGC API standards and the STAC API specification. openEO adds relatively broadly defined conformance classes, especially for the extensions. Otherwise, the implemented functionality can usually be retrieved from - the [capabilties](#tag/Capabilities/operation/capabilities) in openEO. + the [capabilities](#tag/Capabilities/operation/capabilities) in openEO. The general openEO conformance class is `https://api.openeo.org/1.2.0`. See the individual openEO API extensions for their conformance classes. @@ -1614,7 +1614,7 @@ paths: $schema: https://json-schema.org/draft/2019-09/schema $id: https://openeo.example/api/v1/collections/Sentinel-2A/queryables type: object - title: Sentinel 2A + title: Sentinel-2A properties: 'eo:cloud_cover': title: Cloud Cover @@ -1908,7 +1908,7 @@ paths: - {} responses: '200': - description: Lists the the OpenID Connect Providers. + description: Lists the OpenID Connect Providers. content: application/json: schema: @@ -2225,7 +2225,7 @@ paths: can be used to generate small previews or test user-defined processes before starting a batch job. - Timeouts on either client- or server-side are to be expected for complex + Timeouts on either client-side or server-side are to be expected for complex computations. Back-ends MAY send the openEO error `ProcessGraphComplexity` immediately if the computation is expected to time out. Otherwise requests MAY time-out after a certain amount of time by sending openEO error `RequestTimeout`. @@ -3132,8 +3132,8 @@ paths: duration: type: string description: >- - Estimated duration for the operation. Duration MUST be - specified as a ISO 8601 duration. + Estimated duration for the operation. Duration MUST be specified as an + [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations). example: P1Y2M10DT2H30M size: type: integer @@ -3301,8 +3301,8 @@ paths: example: stac_version: 1.0.0 id: a3cca2b2aa1e3b5b - title: NDVI based on Sentinel 2 - description: Deriving minimum NDVI measurements over pixel time series of Sentinel 2 + title: NDVI based on Sentinel-2 + description: Deriving minimum NDVI measurements over pixel time series of Sentinel-2 license: Apache-2.0 providers: - name: Example Cloud Corp. @@ -4965,9 +4965,8 @@ components: nullable: true step: description: >- - The space between the temporal instances as - [ISO 8601 - duration](https://en.wikipedia.org/wiki/ISO_8601#Durations), + The space between the temporal instances as an + [ISO 8601 Duration](https://en.wikipedia.org/wiki/ISO_8601#Durations), e.g. `P1D`. Use `null` for irregularly spaced steps. type: string @@ -5692,7 +5691,7 @@ components: description: A short description to easily distinguish entities. type: string nullable: true - example: NDVI based on Sentinel 2 + example: NDVI based on Sentinel-2 eo_description: type: string format: commonmark @@ -5703,7 +5702,7 @@ components: [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. nullable: true - example: Deriving minimum NDVI measurements over pixel time series of Sentinel 2 + example: Deriving minimum NDVI measurements over pixel time series of Sentinel-2 process_description: type: string format: commonmark From 0f81fd8b3ccd446f90c6c3eea87755559537b8de Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 17 Dec 2024 12:29:17 +0100 Subject: [PATCH 29/52] Clarified the behaviour of `federation:backends` for `POST /validation` (#552) * Clarified the behaviour of `federation:backends` for `POST /validation` * Update extensions/federation/README.md Co-authored-by: Stefaan Lippens --------- Co-authored-by: Stefaan Lippens --- CHANGELOG.md | 1 + extensions/federation/README.md | 16 ++++++++++++++-- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c2a179ec..483613c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `GET /services/{service_id}` and `GET /jobs/{job_id}`: Explicitly allow listing back-end specific properties (as provided in `POST`) - Clarified for log levels which default values apply - Clarified how the relation types `license`, `version-history` and `author` can be used to enrich the process metadata. [#531](https://github.com/Open-EO/openeo-api/issues/531) +- Clarified the behaviour of `federation:backends` for `POST /validation` ## [1.2.0] - 2021-05-25 diff --git a/extensions/federation/README.md b/extensions/federation/README.md index 4e846125..5db430b5 100644 --- a/extensions/federation/README.md +++ b/extensions/federation/README.md @@ -164,11 +164,11 @@ Every discoverable resource that is defined as an object and allows to contain a - `GET /file_formats` (per file format) - `GET /service_types` (per service) - `GET /udf_runtimes` (per UDF runtime, per version) -- `POST /validation` (the back-ends that can run the process) +- `POST /validation` (the back-ends that can run the process, see below) - `GET /process_graphs/{id}` - `GET /jobs/{job_id}` (the back-ends that generated the result) - `GET /jobs/{job_id}/results` (the back-ends that generated the result) -- `GET /services/{id}` +- `GET /services/{id}` (the back-ends that host the service) This can also be embedded deeply into a hierarchical structure, e.g. for process or file format parameters. @@ -189,6 +189,18 @@ schema: **Note:** In Collections this should generally be provided on the top-level of the object. +### Validation + +If this property is returned through the `POST /validation` endpoint, it has the meaning as listed below. +This also covers the case where the federation supports splitting a process into pieces so that different parts can run on different back-ends. + +- Endpoint returns *without* errors: + - `federation:backends` is included in the response: The listed back-ends support the workflow (either partially if splitting is supported, or in full). + - `federation:backends` is *not* included in the response: At least one of the back-ends support the workflow. +- Endpoint returns errors: + - `federation:backends` is included in the response: The listed back-ends were checked and none of the back-ends can run the workflow as is (neither splitted if supported, nor in full). + - `federation:backends` is *not* included in the response: the workflow could not be validated successfully by any of the back-ends or the federation component itself. + ### Examples #### Process From d5ba2808c26d37f33fe1c907e75c11f0a16bb2b0 Mon Sep 17 00:00:00 2001 From: pvbouwel <463976+pvbouwel@users.noreply.github.com> Date: Wed, 18 Dec 2024 12:29:57 +0100 Subject: [PATCH 30/52] doc: use AWS vocabulary in AWS example (#554) When using AWS S3 buckets (provided by AWS or by another S3-compliant provider) in most cases access is not controlled using username & password combination but instead an aws_access_key_id & aws_secret_access_key (optionally an aws_session_token). Co-authored-by: Peter Van Bouwel --- extensions/workspaces/openapi.yaml | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/extensions/workspaces/openapi.yaml b/extensions/workspaces/openapi.yaml index e0115195..b4a72836 100644 --- a/extensions/workspaces/openapi.yaml +++ b/extensions/workspaces/openapi.yaml @@ -114,15 +114,19 @@ paths: title: Amazon S3 description: >- Amazon S3 is a cloud storage service provided by Amazon Web Services. + It provides storage containers which are called buckets. intents: - create - register parameters: - username: - title: Username + aws_access_key_id: + title: AWS access key type: string - password: - title: Password + aws_secret_access_key: + title: AWS secret key associated with the access key. + type: string + bucket_name: + title: Bucket name type: string links: [] /workspaces: @@ -374,13 +378,14 @@ components: workspace_parameters: type: object description: >- - Additional parameters to register the workspace as defined in `GET /workspace_types`. + Additional parameters to register the workspace as defined in `GET /workspace_providers`. The structure is not specified by the API. additionalProperties: description: Any type example: - username: john_doe - password: secret123 + aws_access_key_id: AKIAI0A0FAKE0EXAMPLE + aws_secret_access_key: TheKey1CorrespondingtoAccessKey. + bucket_name: my-bucket123 workspace_properties: type: object description: >- From 4250e313dd1e675f6260b3db0eb337b352aecb54 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Thu, 19 Dec 2024 00:25:12 +0100 Subject: [PATCH 31/52] Issue #508 Clarify updating expiration of signed URL (#516) Co-authored-by: Matthias Mohr --- CHANGELOG.md | 1 + openapi.yaml | 6 ++++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 483613c8..d6a55776 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `GET /file_formats`: Base paramater on top of normal JSON Schema, not Process JSON Schema - `PATCH /services/{service_id}` and `PATCH /jobs/{job_id}`: Explicitly allow updating back-end specific properties (as in `POST`) - `GET /services/{service_id}` and `GET /jobs/{job_id}`: Explicitly allow listing back-end specific properties (as provided in `POST`) +- `GET /jobs/{job_id}/results`: Clarify that signed URLs (used as "canonical" link) should be regenerated each time. - Clarified for log levels which default values apply - Clarified how the relation types `license`, `version-history` and `author` can be used to enrich the process metadata. [#531](https://github.com/Open-EO/openeo-api/issues/531) - Clarified the behaviour of `federation:backends` for `POST /validation` diff --git a/openapi.yaml b/openapi.yaml index 52313981..22603a2d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4033,9 +4033,11 @@ components: default. It is **strongly recommended** to add a link with relation type - `canonical`, which points to this STAC document using a signed URL. - This way the STAC metadata can be used by non-openEO clients + `canonical` pointing to this STAC document using a signed URL. + This signed URL allows consumption of the STAC metadata + by (possibly non-openEO) clients and tools without additional authentication steps. + It is recommended to regenerate the signed URL (and its expiry) with each request. For relation types see the lists of [common relation types in openEO](#section/API-Principles/Web-Linking). From b35c032283a8cbb7fb34ac367c126e87fa30b10f Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Mon, 13 Jan 2025 16:16:39 +0100 Subject: [PATCH 32/52] Add "OpenEO-Identifier" header to synchronous processing response (#533) * Add "OpenEO-Identifier" header to synchronous processing response * Update openapi.yaml Co-authored-by: Matthias Mohr --------- Co-authored-by: Matthias Mohr Co-authored-by: Matthias Mohr --- CHANGELOG.md | 3 ++- openapi.yaml | 6 ++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d6a55776..703a8725 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,10 +11,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **New extensions:** - [Remote Process Definition Extension](./extensions/remote-process-definition/README.md) - Added `version` property to `GET /processes` [#517](https://github.com/Open-EO/openeo-api/issues/517) +- `POST /result`: Added response header "OpenEO-Identifier" to expose an identifier associated with a synchronous processing request. ### Fixed -- `GET /file_formats`: Base paramater on top of normal JSON Schema, not Process JSON Schema +- `GET /file_formats`: Base parameter on top of normal JSON Schema, not Process JSON Schema - `PATCH /services/{service_id}` and `PATCH /jobs/{job_id}`: Explicitly allow updating back-end specific properties (as in `POST`) - `GET /services/{service_id}` and `GET /jobs/{job_id}`: Explicitly allow listing back-end specific properties (as provided in `POST`) - `GET /jobs/{job_id}/results`: Clarify that signed URLs (used as "canonical" link) should be regenerated each time. diff --git a/openapi.yaml b/openapi.yaml index 22603a2d..255bc6b0 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2261,6 +2261,12 @@ paths: description: MAY include the costs for processing and downloading the data. schema: $ref: '#/components/schemas/money' + OpenEO-Identifier: + description: Optionally, an identifier associated with the synchronous processing request. + schema: + type: string + pattern: '^[\w\-\.~]+$' + example: a3cca2b2aa1e3b5b Link: description: >- The header MAY indicate a link to a log file generated by the request. If provided, the link MUST be serialized according to [RFC 8288](https://www.rfc-editor.org/rfc/rfc8288.html#section-3) and MUST use the relation type `monitor`. The link MUST follow the specifications for the links `GET /jobs/{job_id}/logs` and `GET /services/{service_id}/logs`, except that is MUST NOT accept any parameters (limit/offset). Therefore, the link MUST be accessible with HTTP GET, MUST be secured using a Bearer token and MUST follow the corresponding request body schema. From 642f4d64d49673c7305fcb8dba02220f24606d2a Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Mon, 3 Feb 2025 23:54:39 +0100 Subject: [PATCH 33/52] Fixup changelog on `level` property in sync processing request/response (#557) refs: #329, #485 --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 703a8725..311668ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,9 +41,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Recommendation to add a link with relation type `canonical` which points to a signed URL with the same content as the response. [#397](https://github.com/Open-EO/openeo-api/issues/397) - Added metadata field `openeo:status` to indicate the job status (and whether the result is complete or not). - Added parameter `partial` to allow retrieving incomplete results, which must also add the new property `openeo:status` to the metadata. [#430](https://github.com/Open-EO/openeo-api/issues/430) -- `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs`: Added `level` parameter to requests to set the minimum log level returned by the response. [#485](https://github.com/Open-EO/openeo-api/issues/485) +- `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs` and `POST /result`: Added `level` parameter to requests to set the minimum log level returned by the response. [#485](https://github.com/Open-EO/openeo-api/issues/485) - Added property `log_level` to secondary web service, batch job and synchronous processing endpoints to indicate the minimum severity level that should be stored for logs. [#329](https://github.com/Open-EO/openeo-api/issues/329) -- `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs` and `POST /result`: Added `level` property in responses to reflect the minimum log level that may appear in the response. [#329](https://github.com/Open-EO/openeo-api/issues/329) +- `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs`: Added `level` property in responses to reflect the minimum log level that may appear in the response. [#329](https://github.com/Open-EO/openeo-api/issues/329) - Recommendation to add media types and titles to links for a better user experience. - Allow the relation type `canonical` to be used generally for (shared) resources (e.g. UDPs or batch jobs) without requiring Bearer authentication. [#405](https://github.com/Open-EO/openeo-api/issues/405) - Recommendation for UDF runtime names. [#409](https://github.com/Open-EO/openeo-api/issues/409) From e4f607a4f7697d4f1b7bd24472377c4e368d8891 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 6 Feb 2025 18:46:24 +0100 Subject: [PATCH 34/52] Processing Parameters Extension #276 #545 (#471) * Jobs and services: Added `create_parameters` property in responses to define the parameters that can be submitted suring creation #276 * Add processing options to a separate endpoint #276 * Options should be optional * Move to an extension * Add UDP extension * Apply suggestions from code review Co-authored-by: Stefaan Lippens * Renamed according to PR review * Clarify where UDPs can come from * Apply suggestions from code review * Add example * Update extensions/processing-parameters/README.md Co-authored-by: Stefaan Lippens --------- Co-authored-by: Stefaan Lippens --- CHANGELOG.md | 1 + README.md | 1 + .../processing-parameters/.spectral.yml | 12 +++ extensions/processing-parameters/README.md | 75 +++++++++++++ extensions/processing-parameters/openapi.yaml | 100 ++++++++++++++++++ extensions/processing-parameters/package.json | 24 +++++ .../remote-process-definition/README.md | 7 +- 7 files changed, 217 insertions(+), 3 deletions(-) create mode 100644 extensions/processing-parameters/.spectral.yml create mode 100644 extensions/processing-parameters/README.md create mode 100644 extensions/processing-parameters/openapi.yaml create mode 100644 extensions/processing-parameters/package.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 311668ef..fae8a09c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **New extensions:** - [Remote Process Definition Extension](./extensions/remote-process-definition/README.md) + - [Processing Parameters Extension](./extensions/processing-parameters/README.md) - Added `version` property to `GET /processes` [#517](https://github.com/Open-EO/openeo-api/issues/517) - `POST /result`: Added response header "OpenEO-Identifier" to expose an identifier associated with a synchronous processing request. diff --git a/README.md b/README.md index 9917cdfa..f677fee1 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ See also the [changelog](CHANGELOG.md) and the [milestones](https://github.com/O | ------------------------------------------------------------------ | ------- | ------------ | ----------- | | [Commercial Data](extensions/commercial-data/) | 0.1.0 | experimental | Provides an interface for discovering, ordering and using commercial data. | | [Federation](extensions/federation/) | 0.1.0 | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. | +| [Processing Parameters](extensions/processing-parameters/) | 0.1.0 | experimental | Explore and handle additional processing parameters that a back-end can offer for the processing modes (sync. processing, batch jobs, web services). | | [Remote Process Definition](extensions/remote-process-definition/) | 0.1.0 | experimental | Load user-defined processes that are hosted externally through the process namespace into process graphs. | ## Repository diff --git a/extensions/processing-parameters/.spectral.yml b/extensions/processing-parameters/.spectral.yml new file mode 100644 index 00000000..ad10553b --- /dev/null +++ b/extensions/processing-parameters/.spectral.yml @@ -0,0 +1,12 @@ +extends: "spectral:oas" +rules: + contact-properties: true + tag-description: true + oas3-parameter-description: true + oas3-unused-component: true + operation-id-kebab-case: + given: "$..operationId" + then: + function: pattern + functionOptions: + match: ^[a-z][a-z0-9\-]*$ \ No newline at end of file diff --git a/extensions/processing-parameters/README.md b/extensions/processing-parameters/README.md new file mode 100644 index 00000000..6de468b3 --- /dev/null +++ b/extensions/processing-parameters/README.md @@ -0,0 +1,75 @@ +# Processing Parameters Extension + +The Processing Parameters Extension to the openEO API provides an interface to explore and handle additional processing parameters that a back-end can offer for the three processing modes (synchronous processing, batch jobs, secondary web services). + +- Version: **0.1.0** +- Stability: **experimental** +- [OpenAPI document](openapi.yaml) +- Conformance class: `https://api.openeo.org/extensions/processing-parameters/0.1.0` + +**Note:** This document only documents the additions to the specification. +Extensions can not change or break existing behavior of the openEO API. + +This extension adds a new endpoint (`GET /processing_parameters`, see [OpenAPI document](openapi.yaml)) +to discover the additional processing parameters that a back-end offers. + +Additionally, this extension allows to provide specific default values for user-defined processes (UDPs), +which includes: + +- UDPs submitted directly for synchronous processing, as batch jobs, or as secondary web services +- UDPs stored through the `/process_graphs` endpoints +- UDPs stored external to the API and retrieved through the [Remote Process Definition Extension](../remote-process-definition/README.md) + +The parameters and its values are provided separately for each processing mode. + +## Embedding default processing options in UDPs + +UDPs can provide default values for specific processing parameters. + +The values for each parameter (so called 'options') are provided separately for each processing mode. +The following properties are added to the top-level of a UDP (e.g. as sibling nodes to the "process_graph" property) for the respective processing modes: + +- `default_synchronous_options` for synchronous processing +- `default_job_options` for batch jobs +- `default_service_options` for secondary web services + +The schema for each of these properties is: + +```yaml +type: object +additionalProperties: + description: Any type +``` + +The keys of the object are the respective parameter names. +The values of the object are the default values for the parameters. +Schematic restrictions are not defined for the object, but the schemas for the parameters as defined in `GET /processing_parameters` apply to the given values. +These values provide the defaults unless a user overrides them in the actual data processing request (e.g. `POST /jobs`, see below). + +Example UDP including defaults for the processing parameters `memory` and `block-sizes` of a batch job: + +```json +{ + "id": "my_evi", + "parameters": [...], + "process_graph": {...}, + "default_job_options": { + "memory": "2GB", + "block-sizes": [128, 32] + } +} +``` + +## Resolving parameters + +Due to the variety of places where processing parameters can be provided, the following +list defines how the parameters must be resolved. The prioritization is as follows: + +1. If present, use the parameter specified in the processing request directly (e.g. in `POST /jobs` as a top-level property) +2. If present, use the default parameter specified in the UDP +3. Otherwise, use the default value for the parameter as specified in `GET /processing_parameters` + +"Present" means that the property is present in the JSON representation regardless of the value given, i.e. +properties are present if an empty string, an empty array, an empty object, `false`, `0`, or `null` are provided. + +Unrecognized/unknown parameters that are provided through UDPs must be ignored by backends. diff --git a/extensions/processing-parameters/openapi.yaml b/extensions/processing-parameters/openapi.yaml new file mode 100644 index 00000000..4b188266 --- /dev/null +++ b/extensions/processing-parameters/openapi.yaml @@ -0,0 +1,100 @@ +openapi: 3.0.2 +info: + title: openEO API - Processing Parameters Extension + version: 0.1.0 + description: >- + The Processing Parameters Extension to the openEO API provides an interface to explore and handle additional processing parameters that a back-end can offer for the three processing modes (synchronous processing, batch jobs, and secondary web services). + The openEO API specification allows back-ends to accept "additional back-end specific properties" for each of the processing modes. + As the openEO API specification does not define the name and schemas of these properties, this extension provides a standardized way to define and document these properties. + contact: + name: openEO Consortium + url: 'https://openeo.org' + email: openeo.psc@uni-muenster.de + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' +externalDocs: + url: https://github.com/Open-EO/openeo-api/blob/draft/extensions/workspaces/README.md +tags: + - name: Capabilities + description: General information about the API implementation and other supported capabilities provided by the back-end. + - name: Data Processing + description: Organizes and manages data processing on the back-end, either as synchronous on-demand computation or batch jobs. + - name: Batch Jobs + description: Management of batch processing tasks (jobs) and their results. + - name: Secondary Services + description: On-demand access to data using other web service protocols. +servers: + - url: 'https://openeo.example/api/{version}' + description: >- + The URL of the API MAY freely be chosen by the back-end providers. The + path, including API versioning, is a *recommendation* only. Nevertheless, + all servers MUST support HTTPS as the authentication methods are not + secure with HTTP only! + variables: + version: + default: v1 + description: >- + API versioning is RECOMMENDED. As the openEO API is following + [SemVer](https://semver.org/) only the MAJOR part of the stable + version numbers (i.e. versions >= 1.0.0) SHOULD be used for API + versioning in the URL. The reason is that backward-incompatible + changes are usually introduced by major changes. Therefore, the + version number in the URL MUST not be used by the clients to detect + the version number of the API. Use the version number returned from + `GET /` instead. +paths: + /processing_parameters: + get: + summary: Additional processing parameters + operationId: list-processing-parameters + description: |- + Lists additional custom processing parameters + that a back-end offers for the different processing modes (synchronous processing, batch jobs, secondary web services). + The parameters specified here can be added to the corresponding `POST` requests at the top-level of the object that is sent as the payload. + All parameters SHOULD explicitly be made optional with reasonable defaults as otherwise the interoperability between the implementations decreases. + tags: + - Capabilities + - Data Processing + - Batch Jobs + - Secondary Services + security: + - {} + - Bearer: [] + responses: + '200': + description: >- + An object with a list of parameters per processing mode. + content: + application/json: + schema: + description: Processing parameters per processing mode. + type: object + properties: + create_job_parameters: + $ref: '#/components/schemas/processing_create_parameters' + create_service_parameters: + $ref: '#/components/schemas/processing_create_parameters' + create_synchronous_parameters: + $ref: '#/components/schemas/processing_create_parameters' +components: + schemas: + processing_create_parameters: + title: Creation Parameters + description: |- + List of additional custom parameters that a back-end offers during the creation + of batch jobs (`POST /jobs`) and secondary web services (`POST /services`) respectively. + type: array + items: + $ref: '../../openapi.yaml#/components/schemas/parameter' + example: + - name: memory + description: Maximum amount of memory that will be allocated for processing, in gigabytes. + optional: true + default: 32 + schema: + type: integer + minimum: 1 + securitySchemes: + Bearer: + $ref: '../../openapi.yaml#/components/securitySchemes/Bearer' diff --git a/extensions/processing-parameters/package.json b/extensions/processing-parameters/package.json new file mode 100644 index 00000000..841560a5 --- /dev/null +++ b/extensions/processing-parameters/package.json @@ -0,0 +1,24 @@ +{ + "name": "@openeo/api-extension-processing-parameters", + "version": "0.1.0", + "author": "openEO Consortium", + "license": "Apache-2.0", + "description": "The openEO API specification.", + "homepage": "https://openeo.org", + "bugs": { + "url": "https://github.com/Open-EO/openeo-api/issues" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/Open-EO/openeo-api.git" + }, + "devDependencies": { + "@stoplight/spectral-cli": "^6.6.0", + "redoc-cli": "^0.13.21" + }, + "scripts": { + "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", + "build": "redoc-cli bundle openapi.yaml -o redoc.html --title \"openEO API - Processing Parameters Extension\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", + "test": "spectral lint openapi.yaml" + } +} diff --git a/extensions/remote-process-definition/README.md b/extensions/remote-process-definition/README.md index 7ee7f76e..17046f9e 100644 --- a/extensions/remote-process-definition/README.md +++ b/extensions/remote-process-definition/README.md @@ -13,9 +13,10 @@ This extension enables user to load user-defined processes that are hosted exter The openEO API defines the `namespace` property in a process node of a process graph as follows: > The following options are predefined by the openEO API, but additional namespaces may be introduced by back-ends or in a future version of the API. -> * `null` [...] -> * `backend` [...] -> * `user` [...] +> +> - `null` [...] +> - `backend` [...] +> - `user` [...] This makes it possible for this extension to add additional allowed values to the `namespace` property. From 5d356f7bb80a62f61047ec8447d4ab05b04fc6f5 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 14 Feb 2025 21:39:23 +0100 Subject: [PATCH 35/52] Add additional batch job timestamps (#556) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Added `queued`, `started` and `expires` to the batch job metadata and the corresponding STAC results. #542 * Apply suggestions from code review Co-authored-by: Serge Croisé * Apply suggestions from code review Co-authored-by: Serge Croisé * Update according to review, also add to Collection result type * Apply suggestions from code review Co-authored-by: Serge Croisé * Typo --------- Co-authored-by: Serge Croisé --- CHANGELOG.md | 5 +++- openapi.yaml | 76 ++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 69 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fae8a09c..6fe2d970 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,8 +11,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **New extensions:** - [Remote Process Definition Extension](./extensions/remote-process-definition/README.md) - [Processing Parameters Extension](./extensions/processing-parameters/README.md) -- Added `version` property to `GET /processes` [#517](https://github.com/Open-EO/openeo-api/issues/517) - `POST /result`: Added response header "OpenEO-Identifier" to expose an identifier associated with a synchronous processing request. +- Added `version` property to `GET /processes` [#517](https://github.com/Open-EO/openeo-api/issues/517) +- Added `queued`, `started` and `unpublished` to the batch job metadata and the corresponding STAC results [#542](https://github.com/Open-EO/openeo-api/issues/542) +- Added all the batch job timestamps (including the new timestamps above) to the Collection type of batch job results ### Fixed @@ -23,6 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Clarified for log levels which default values apply - Clarified how the relation types `license`, `version-history` and `author` can be used to enrich the process metadata. [#531](https://github.com/Open-EO/openeo-api/issues/531) - Clarified the behaviour of `federation:backends` for `POST /validation` +- Clarified the meaning of `expires` in batch job results ## [1.2.0] - 2021-05-25 diff --git a/openapi.yaml b/openapi.yaml index 255bc6b0..88955568 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -3300,6 +3300,18 @@ paths: required: - assets properties: + created: + $ref: '#/components/schemas/created' + updated: + $ref: '#/components/schemas/updated' + queued: + $ref: '#/components/schemas/queued' + started: + $ref: '#/components/schemas/started' + expires: + $ref: '#/components/schemas/expires' + unpublished: + $ref: '#/components/schemas/unpublished' 'openeo:status': $ref: '#/components/schemas/result_status' allOf: @@ -4002,7 +4014,7 @@ components: format: date-time description: >- For time series: The last or end date and time for the data, in - UTC. Formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) + UTC. Formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. title: $ref: '#/components/schemas/eo_title' @@ -4016,13 +4028,14 @@ components: $ref: '#/components/schemas/created' updated: $ref: '#/components/schemas/updated' + queued: + $ref: '#/components/schemas/queued' + started: + $ref: '#/components/schemas/started' expires: - type: string - format: date-time - description: >- - Time until which the assets are accessible, in UTC. Formatted as - a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. - example: '2020-11-01T00:00:00Z' + $ref: '#/components/schemas/expires' + unpublished: + $ref: '#/components/schemas/unpublished' 'openeo:status': $ref: '#/components/schemas/result_status' assets: @@ -5321,6 +5334,7 @@ components: parameters: type: array nullable: true + items: {} returns: type: object nullable: true @@ -5345,6 +5359,7 @@ components: parameters: type: array nullable: true + items: {} returns: type: object nullable: true @@ -5604,6 +5619,12 @@ components: $ref: '#/components/schemas/created' updated: $ref: '#/components/schemas/updated' + queued: + $ref: '#/components/schemas/queued' + started: + $ref: '#/components/schemas/started' + unpublished: + $ref: '#/components/schemas/unpublished' plan: $ref: '#/components/schemas/billing_plan' costs: @@ -5666,16 +5687,49 @@ components: type: string format: date-time description: >- - Date and time of creation, formatted as a [RFC - 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + Date and time of creation (for batch jobs: the status 'created' was set), + formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. example: '2017-01-01T09:32:12Z' updated: type: string format: date-time description: >- - Date and time of the last status change, formatted as a [RFC - 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + Date and time of the last status change, + formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + If the status is `error`, `canceled` or `finished`, + this is the time when the job has ended. + example: '2017-01-01T09:54:18Z' + queued: + type: string + format: date-time + description: >- + Date and time of queueing the batch job (i.e., when the status 'queued' was set), + formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + example: '2017-01-01T09:34:00Z' + started: + type: string + format: date-time + description: >- + Date and time when the batch job started processing (i.e., when the status 'running' was set), + formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. example: '2017-01-01T09:36:18Z' + expires: + type: string + format: date-time + description: >- + Time in UTC until which the assets and this document are accessible via the signed URL + that is provided with the relation type `canonical` in the links. + Formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + After expiration, a document with new signed URLs can be retrieved through an authenticated + request to this endpoint. + example: '2017-02-01T09:54:18Z' + unpublished: + type: string + format: date-time + description: >- + Time until which the batch job results are stored on the back-end, in UTC. + Formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + example: '2018-01-01T09:54:18Z' description: type: string format: commonmark From f7afd4909fb7d4bf3ad1041e4543c9b17df63ff9 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Fri, 14 Feb 2025 21:40:17 +0100 Subject: [PATCH 36/52] Issue #507: clarify that "canonical" job result link should include query parameters (#513) * Issue #507: clarify that "canonical" job result link should include query parameters * Issue #507/#513 improve clarification of including query parameters in canonical URL --------- Co-authored-by: Matthias Mohr --- CHANGELOG.md | 1 + openapi.yaml | 3 +++ 2 files changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6fe2d970..42b4ef27 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `PATCH /services/{service_id}` and `PATCH /jobs/{job_id}`: Explicitly allow updating back-end specific properties (as in `POST`) - `GET /services/{service_id}` and `GET /jobs/{job_id}`: Explicitly allow listing back-end specific properties (as provided in `POST`) - `GET /jobs/{job_id}/results`: Clarify that signed URLs (used as "canonical" link) should be regenerated each time. +- `GET /jobs/{job_id}/results`: Clarify that "canonical" job result link should include/encode the original query parameters - Clarified for log levels which default values apply - Clarified how the relation types `license`, `version-history` and `author` can be used to enrich the process metadata. [#531](https://github.com/Open-EO/openeo-api/issues/531) - Clarified the behaviour of `federation:backends` for `POST /validation` diff --git a/openapi.yaml b/openapi.yaml index 88955568..6136a335 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4053,6 +4053,9 @@ components: It is **strongly recommended** to add a link with relation type `canonical` pointing to this STAC document using a signed URL. + Note that query parameters that influence the response of the current request + (like `partial`) MUST also be included or encoded within the signed URL + in order to give a consistent response when the signed URL is used. This signed URL allows consumption of the STAC metadata by (possibly non-openEO) clients and tools without additional authentication steps. From 556d9cbfcabe824f072a5c13b2bfc33d72bbe301 Mon Sep 17 00:00:00 2001 From: Stefaan Lippens Date: Wed, 19 Mar 2025 13:22:48 +0100 Subject: [PATCH 37/52] Federation extension: nullable last_successful_check (#560) * Federation extension: nullable last_successful_check when back-end was never observed to be available * Update extensions/federation/README.md Co-authored-by: Matthias Mohr * PR #560 add changelog entry --------- Co-authored-by: Matthias Mohr --- CHANGELOG.md | 1 + extensions/federation/README.md | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 42b4ef27..d19374a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Clarified how the relation types `license`, `version-history` and `author` can be used to enrich the process metadata. [#531](https://github.com/Open-EO/openeo-api/issues/531) - Clarified the behaviour of `federation:backends` for `POST /validation` - Clarified the meaning of `expires` in batch job results +- Clarified that `last_successful_check` (from Federation Extension) can be null. ## [1.2.0] - 2021-05-25 diff --git a/extensions/federation/README.md b/extensions/federation/README.md index 5db430b5..a68816a6 100644 --- a/extensions/federation/README.md +++ b/extensions/federation/README.md @@ -61,8 +61,10 @@ schema: last_successful_check: type: string format: date-time + nullable: true description: >- - If the `status` is `offline`: The time at which the back-end was checked and available the last time. + If the `status` is `offline`: The time at which the back-end was checked and available the last time + or `null` when the back-end was never observed to be available. Otherwise, this is equal to the property `last_status_check`. experimental: type: boolean From da9bf27f79a428d2404ed9fe58dd9ad5d0b467a7 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 10 Apr 2025 16:40:19 +0200 Subject: [PATCH 38/52] Update README.md --- extensions/federation/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/extensions/federation/README.md b/extensions/federation/README.md index a68816a6..dba45ee2 100644 --- a/extensions/federation/README.md +++ b/extensions/federation/README.md @@ -159,7 +159,8 @@ schema: ## Resources supported only by a subset of back-ends -Every discoverable resource that is defined as an object and allows to contain additional properties, can list the back-ends that support or host the exposed resource/functionality. Examples of where this could apply to (**not** comprehensive): +Every discoverable resource that is defined as an object and allows to contain additional properties, can list the subset of back-ends that support or host the exposed resource/functionality. +Examples of where this could apply to (**not** comprehensive): - `GET /collections/{id}` - `GET /processes` (per process, per parameter) @@ -180,7 +181,7 @@ schema: properties: 'federation:backends': description: >- - Lists all back-ends that support or host the resource. + Lists the subset of back-ends that support or host the resource. If not given, all back-ends support the resource. type: array minItems: 1 @@ -238,4 +239,4 @@ This also covers the case where the federation supports splitting a process into "federation:backends": ["vito", "eodc"], ... } -``` \ No newline at end of file +``` From 18d88827b45aa91ae1c28cda17e3e9fdb86a47fb Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 1 Jul 2025 10:49:56 +0200 Subject: [PATCH 39/52] Clarify federation extension fields (#564) Co-authored-by: Christoph Friedrich Co-authored-by: Stefaan Lippens --- extensions/federation/README.md | 119 +++++++++++++++++--------------- 1 file changed, 65 insertions(+), 54 deletions(-) diff --git a/extensions/federation/README.md b/extensions/federation/README.md index dba45ee2..68c16d0c 100644 --- a/extensions/federation/README.md +++ b/extensions/federation/README.md @@ -106,71 +106,27 @@ schema: } ``` -## Lists of resources +## Resources supported only by a subset of back-ends -Clients will assume that all lists of resources are the a combination of all back-ends listed in `GET /`. -Federated APIs can expose if any of the back-ends is not available and thus is not part of the response. +Discoverable resources can explicitly list the subset of back-ends that support or host the exposed resource or functionality with the property `federation:backends`. -Applies to: +Schema-wise, this only applies to resources that are defined as an object and allow to contain additional properties. +For example (**not** comprehensive): - `GET /collections` -- `GET /processes` -- `GET /file_formats` -- `GET /process_graphs` -- `GET /files` -- `GET /jobs` -- `GET /jobs/{job_id}` -- `GET /jobs/{job_id}/results` -- `GET /jobs/{job_id}/logs` -- `GET /services` - -The following endpoints define the resources (UDF runtimes / service types) at the top level of their response as key-value pairs. -Consequently, they are not extensible with additional properties for federation purposes. - -- `GET /udf_runtimes` -- `GET /service_types` - -### OpenAPI fragment - -```yaml -schema: - type: object - properties: - 'federation:missing': - description: >- - Lists all back-ends that were not considered in the response (e.g. because they were not accessible). - If not given or empty, all back-ends were considered for creating the response. - Back-ends that were listed as offline in the capabilities still need to be listed here. - type: array - items: - type: string - description: The ID of a back-end. -``` - -### Example - -```json -{ - "federation:missing": ["wwu"], - "collections": [...], - "links": [...] -} -``` - -## Resources supported only by a subset of back-ends - -Every discoverable resource that is defined as an object and allows to contain additional properties, can list the subset of back-ends that support or host the exposed resource/functionality. -Examples of where this could apply to (**not** comprehensive): - - `GET /collections/{id}` -- `GET /processes` (per process, per parameter) -- `GET /file_formats` (per file format) +- `GET /processes` (global, per process, per parameter) +- `GET /file_formats` (global, per file format) - `GET /service_types` (per service) - `GET /udf_runtimes` (per UDF runtime, per version) - `POST /validation` (the back-ends that can run the process, see below) +- `GET /files` +- `GET /process_graphs` - `GET /process_graphs/{id}` +- `GET /jobs` - `GET /jobs/{job_id}` (the back-ends that generated the result) - `GET /jobs/{job_id}/results` (the back-ends that generated the result) +- `GET /services` - `GET /services/{id}` (the back-ends that host the service) This can also be embedded deeply into a hierarchical structure, e.g. for process or file format parameters. @@ -240,3 +196,58 @@ This also covers the case where the federation supports splitting a process into ... } ``` + +## Temporarily or unintentionally unavailable resources + +Resources and back-ends can be temporarily or unintentionally unavailable. +It is especially important to communicate to users missing resources when compiling a **list of resources** across multiple back-ends. +Clients will assume that all lists of resources are a combination of all back-ends listed under `federation` in `GET /`. +Federated APIs can expose if any of the back-ends was not available when building the resource listing response with the property `federation:missing`. + +Examples of where this could apply to (**not** comprehensive): + +- `GET /collections` +- `GET /processes` +- `GET /file_formats` +- `GET /process_graphs` +- `GET /files` +- `GET /jobs` +- `GET /jobs/{job_id}` +- `GET /jobs/{job_id}/results` +- `GET /jobs/{job_id}/logs` +- `GET /services` + +### OpenAPI fragment + +```yaml +schema: + type: object + properties: + 'federation:missing': + description: >- + Lists all back-ends that were unexpectedly unavailable during compilation of the response. + If not given or empty, all back-ends supporting this endpoint were considered for creating the response. + Back-ends that are listed as offline in the capabilities still need to be listed here. + type: array + items: + type: string + description: The ID of a back-end. +``` + +### Example + +```json +{ + "federation:missing": ["wwu"], + "collections": [...], + "links": [...] +} +``` + +## Endpoints that can't list federation details + +The following endpoints define the resources (UDF runtimes / service types) at the top level of their response as key-value pairs. +Consequently, they are not extensible with additional properties for federation purposes. + +- `GET /udf_runtimes` +- `GET /service_types` From 85a0e9a193c9d672d5a0763059e6ae543d1fa4f5 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 1 Jul 2025 12:18:57 +0200 Subject: [PATCH 40/52] Federation extension: What means "successfully validated"? #563 --- extensions/federation/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extensions/federation/README.md b/extensions/federation/README.md index 68c16d0c..02253179 100644 --- a/extensions/federation/README.md +++ b/extensions/federation/README.md @@ -158,7 +158,7 @@ This also covers the case where the federation supports splitting a process into - `federation:backends` is *not* included in the response: At least one of the back-ends support the workflow. - Endpoint returns errors: - `federation:backends` is included in the response: The listed back-ends were checked and none of the back-ends can run the workflow as is (neither splitted if supported, nor in full). - - `federation:backends` is *not* included in the response: the workflow could not be validated successfully by any of the back-ends or the federation component itself. + - `federation:backends` is *not* included in the response: the workflow could not be validated successfully by any of the back-ends or the federation component itself. This includes any kind of failed validation attempt, including network and server errors. ### Examples From 056e31c691dac9050baf94897e2119cd85111503 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 22 Aug 2025 15:25:53 +0200 Subject: [PATCH 41/52] Add openapi.yaml to versioned folders in gh-pages #551 --- .github/workflows/docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c60a86bd..b9d297df 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -31,6 +31,7 @@ jobs: - run: | cp redoc.html gh-pages/index.html cp errors.json gh-pages/errors.json + cp openapi.yaml gh-pages/openapi.yaml cp -rv assets/. gh-pages/assets/ - name: deploy to root (master) uses: peaceiris/actions-gh-pages@v4 From 96609f0ac34a093887d5f0f11e48a4459780466c Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 29 Aug 2025 12:01:38 +0200 Subject: [PATCH 42/52] `GET /udf_runtimes`: Requires at least one UDF runtime to be provided. #511 (#568) --- CHANGELOG.md | 4 ++++ openapi.yaml | 1 + 2 files changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index d19374a0..9cf57e50 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added `queued`, `started` and `unpublished` to the batch job metadata and the corresponding STAC results [#542](https://github.com/Open-EO/openeo-api/issues/542) - Added all the batch job timestamps (including the new timestamps above) to the Collection type of batch job results +### Changed + +- `GET /udf_runtimes`: Requires at least one UDF runtime to be provided. [#511](https://github.com/Open-EO/openeo-api/issues/511) + ### Fixed - `GET /file_formats`: Base parameter on top of normal JSON Schema, not Process JSON Schema diff --git a/openapi.yaml b/openapi.yaml index 6136a335..b4aa53d5 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1810,6 +1810,7 @@ paths: * For programming langauge environments use the names as provided in in the [Scriptol List of Programming Languages](https://www.scriptol.com/programming/list-programming-languages.php). * For docker images use the docker image identifier excluding the registry path. + minProperties: 1 additionalProperties: x-additionalPropertiesName: UDF Runtime name allOf: From 2f931b96ec6e574bc79c1cd07b20b0b623f1b437 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 29 Aug 2025 16:00:58 +0200 Subject: [PATCH 43/52] Update STAC references and deprecate v0.9.0 #543 (#569) --- CHANGELOG.md | 5 +++++ openapi.yaml | 44 ++++++++++++++++++++++---------------------- 2 files changed, 27 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9cf57e50..5f7636f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,8 +16,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added `queued`, `started` and `unpublished` to the batch job metadata and the corresponding STAC results [#542](https://github.com/Open-EO/openeo-api/issues/542) - Added all the batch job timestamps (including the new timestamps above) to the Collection type of batch job results +### Deprecated + +- STAC 0.9.x + ### Changed +- `GET /`: Requires the fields `type` and `conformsTo` - `GET /udf_runtimes`: Requires at least one UDF runtime to be provided. [#511](https://github.com/Open-EO/openeo-api/issues/511) ### Fixed diff --git a/openapi.yaml b/openapi.yaml index b4aa53d5..7ed08b7c 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -510,22 +510,27 @@ tags: ## STAC - For data discovery of Earth Observation Collections at the back-ends, openEO strives for compatibility with the specifications [SpatioTemporal Asset Catalog (STAC)](https://stacspec.org/) and [OGC API - Features - Part 1: Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) as far as possible. Implementing the data discovery endpoints of openEO also produced valid STAC API 1.0 and OGC API - Features 1.0 responses, including ([partial](#provide-data-for-download)) compatibility with their APIs. + For data discovery of Earth Observation Collections at the back-ends, openEO strives for compatibility with the specifications [SpatioTemporal Asset Catalog (STAC)](https://stacspec.org/) and [OGC API - Features - Part 1: Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html) as far as possible. Implementing the data discovery endpoints of openEO also produces valid STAC API 1.x and OGC API - Features 1.x responses, including ([partial](#provide-data-for-download)) compatibility with their APIs. The data discovery endpoints `GET /collections` and `GET /collections/{collection_id}` are compatible with OGC API - Features and STAC. Both specifications define additional endpoints that need to be implemented to be fully compatible. The additional endpoints can easily be integrated into an openEO API implementation. A rough list of actions for compatibility is available below, but please refer to their specifications to find out the full details. - **Important:** [STAC specification](https://github.com/radiantearth/stac-spec) and [STAC API](https://github.com/radiantearth/stac-api-spec) are different specifications and have different version numbers after version 0.9.0. - The openEO API implements STAC API versions >= 0.9.0 (preferrably [STAC API version 1.0.0](https://github.com/radiantearth/stac-api-spec/blob/v1.0.0/README.md), but [0.9.0](https://github.com/radiantearth/stac-spec/blob/v0.9.0/api-spec/README.md) is allowed for backward compatibility), which allows to serve all STAC specification versions in the range of 0.9.x and 1.x.x (see the `stac_version` property). + **Important:** [STAC specification](https://github.com/radiantearth/stac-spec) and [STAC API](https://github.com/radiantearth/stac-api-spec) are different specifications and have different version numbers. + + The openEO API allows for the + - STAC versions 1.x.x (RECOMMENDED) and 0.9.x (DEPRECATED), and + - STAC API versions 1.x.x (RECOMMENDED) and 0.9.x (DEPRECATED). ### Content Extensions STAC has several [extensions](https://stac-extensions.github.io) that can be used to better describe your data. Clients and server are not required to implement all of them, so be aware that some clients may not be able to read all your metadata. Some commonly used extensions that are relevant for datasets exposed through the openEO API are: - - - Data Cube extension (part of the openEO API) + + - [Classification extension](https://github.com/stac-extensions/classification) + - [Data Cube extension](https://github.com/stac-extensions/datacube) (part of the openEO API) - [EO (Electro-Optical) extension](https://github.com/stac-extensions/eo) - [Processing extension](https://github.com/stac-extensions/processing) + - [Projection extension](https://github.com/stac-extensions/projection) - [Raster extension](https://github.com/stac-extensions/raster) - [SAR extension](https://github.com/stac-extensions/sar) - [Satellite extension](https://github.com/stac-extensions/sat) @@ -533,7 +538,7 @@ tags: ### Provide data for download - If you'd like to provide your data for download in addition to offering the cloud processing service, you can implement the full STAC API. Therefore, you can implement the endpoints `GET /collections/{collection_id}/items` and `GET /collections/{collection_id}/items/{feature_id}` to support retrieval of individual items. To benefit from the STAC ecosystem and allow searching for items you can also implement `POST /search` and `GET /search`. Further information can be found in the [STAC API repository](https://github.com/radiantearth/stac-spec/tree/v0.9.0/api-spec). + If you'd like to provide your data for download in addition to offering the cloud processing service, you can implement the full STAC API. Therefore, you can implement the endpoints `GET /collections/{collection_id}/items` and `GET /collections/{collection_id}/items/{feature_id}` to support retrieval of individual items. To benefit from the STAC ecosystem and allow searching for items you can also implement `POST /search` and `GET /search`. Further information can be found in the [STAC API repository](https://github.com/radiantearth/stac-api-spec). ### API Extensions @@ -609,6 +614,8 @@ paths: - api_version - backend_version - stac_version + - conformsTo + - type - endpoints - links properties: @@ -633,8 +640,6 @@ paths: type: string enum: - Catalog - description: >- - For STAC versions >= 1.0.0-rc.1 this field is required. example: Catalog id: type: string @@ -1232,7 +1237,7 @@ paths: To get the full metadata for a collection clients MUST request `GET /collections/{collection_id}`. - This endpoint is compatible with [STAC API 0.9.0 and later](https://stacspec.org) and + This endpoint is compatible with [STAC API 1.0.0 and later](https://stacspec.org) and [OGC API - Features 1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html). [STAC API extensions](https://stac-api-extensions.github.io) and [STAC extensions](https://stac-extensions.github.io) @@ -1362,7 +1367,7 @@ paths: Lists **all** information about a specific collection specified by the identifier `collection_id`. - This endpoint is compatible with [STAC API 0.9.0 and later](https://stacspec.org) and + This endpoint is compatible with [STAC API 1.0.0 and later](https://stacspec.org) and [OGC API - Features 1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html). [STAC API extensions](https://stac-api-extensions.github.io) and [STAC extensions](https://stac-extensions.github.io) @@ -3762,8 +3767,6 @@ components: The general openEO conformance class is `https://api.openeo.org/1.2.0`. See the individual openEO API extensions for their conformance classes. - - This property is REQUIRED for STAC API versions 1.0.0-beta.1 and later. type: array items: type: string @@ -4544,9 +4547,9 @@ components: Potential fields for the summaries can be found here: - * **[STAC Common Metadata](https://github.com/radiantearth/stac-spec/blob/v1.0.0/item-spec/common-metadata.md)**: + * **[STAC Common Metadata](https://github.com/radiantearth/stac-spec/blob/v1.1.0/commons/common-metadata.md)**: A list of commonly used fields throughout all domains - * **[Content Extensions](https://github.com/radiantearth/stac-spec/blob/v1.0.0/extensions/README.md#list-of-content-extensions)**: + * **[Content Extensions](https://stac-extensions.github.io)**: Domain-specific fields for domains such as EO, SAR and point clouds. * **Custom Properties**: It is generally allowed to add custom fields. @@ -4564,9 +4567,6 @@ components: Dictionary of asset objects for data that can be downloaded, each with a unique key. The keys MAY be used by clients as file names. - - Implementing this property REQUIRES to add `collection-assets` - to the list of `stac_extensions` in STAC < 1.0.0-rc.1. allOf: - $ref: '#/components/schemas/stac_assets' stac_version: @@ -4574,15 +4574,15 @@ components: description: >- The [version of the STAC specification](https://github.com/radiantearth/stac-spec/releases), which MAY not be equal to the [STAC API version](#tag/EO-Data-Discovery/STAC). - Supports versions 0.9.x and 1.x.x. + + The openEO API allows for the STAC versions 1.x.x (RECOMMENDED) and 0.9.x (DEPRECATED). pattern: '^(0\.9.\d+|1\.\d+.\d+)' - example: 1.0.0 + example: 1.1.0 stac_extensions: type: array description: >- A list of implemented STAC extensions. The list contains URLs to the - JSON Schema files it can be validated against. For STAC < 1.0.0-rc.1 - shortcuts such as `sar` can be used instead of the schema URL. + JSON Schema files it can be validated against. uniqueItems: true items: anyOf: @@ -4590,7 +4590,7 @@ components: type: string format: uri example: 'https://openeo.example/stac/custom-extemsion/v1.0.0/schema.json' - - title: Reference to a core extension (STAC < 1.0.0-rc.1 only) + - title: Reference to a core extension (STAC < 1.0.0-rc.1 only, DEPRECATED) type: string example: datacube stac_license: From 7a375e13e63c037984eaeea634302f900e09fafa Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 9 Sep 2025 00:15:53 +0200 Subject: [PATCH 44/52] Update redocly, simplify building process, deploy all extensions --- .github/workflows/docs.yml | 11 ++-- .github/workflows/tests.yml | 20 ++----- .gitignore | 11 ++-- .redocly.lint-ignore.yaml | 8 +++ .redocly.yaml | 16 ++++++ CHANGELOG.md | 2 + README.md | 4 +- extensions/commercial-data/.spectral.yml | 12 ---- extensions/commercial-data/openapi.yaml | 4 +- extensions/commercial-data/package.json | 24 -------- .../processing-parameters/.spectral.yml | 12 ---- extensions/processing-parameters/openapi.yaml | 4 ++ extensions/processing-parameters/package.json | 24 -------- extensions/workspaces/.spectral.yml | 12 ---- extensions/workspaces/openapi.yaml | 13 +++-- extensions/workspaces/package.json | 24 -------- openapi.yaml | 55 ++++++------------- package.json | 17 ++++-- 18 files changed, 83 insertions(+), 190 deletions(-) create mode 100644 .redocly.lint-ignore.yaml create mode 100644 .redocly.yaml delete mode 100644 extensions/commercial-data/.spectral.yml delete mode 100644 extensions/commercial-data/package.json delete mode 100644 extensions/processing-parameters/.spectral.yml delete mode 100644 extensions/processing-parameters/package.json delete mode 100644 extensions/workspaces/.spectral.yml delete mode 100644 extensions/workspaces/package.json diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b9d297df..81df2f00 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -12,13 +12,12 @@ jobs: steps: - name: Inject env variables uses: rlespinasse/github-slug-action@v5 - - uses: actions/setup-node@v4 + - uses: actions/setup-node@v5 with: node-version: 'lts/*' - - uses: actions/checkout@v4 - - run: | - npm install - npm run build + - uses: actions/checkout@v5 + - run: npm install + - run: npm run build - name: clone gh-pages and clean-up if: ${{ env.GITHUB_REF_SLUG == 'master' }} run: | @@ -29,7 +28,7 @@ jobs: if: ${{ env.GITHUB_REF_SLUG != 'master' }} run: mkdir gh-pages - run: | - cp redoc.html gh-pages/index.html + cp *.html gh-pages/ cp errors.json gh-pages/errors.json cp openapi.yaml gh-pages/openapi.yaml cp -rv assets/. gh-pages/assets/ diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 905d920b..c2fbcef7 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -4,21 +4,9 @@ jobs: deploy: runs-on: ubuntu-latest steps: - - uses: actions/setup-node@v4 + - uses: actions/setup-node@v5 with: node-version: 'lts/*' - - uses: actions/checkout@v4 - - name: Run core tests - run: | - npm install - npm test - - name: Run commercial-data tests - run: | - cd extensions/commercial-data - npm install - npm test - - name: Run workspaces tests - run: | - cd extensions/workspaces - npm install - npm test \ No newline at end of file + - uses: actions/checkout@v5 + - run: npm install + - run: npm test \ No newline at end of file diff --git a/.gitignore b/.gitignore index 7426e59f..1f3bbe4e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,5 @@ -__pycache__/ -package-lock.json -node_modules/ -/redoc.html -.vscode -.idea +package-lock.json +/node_modules/ +/*.html +.vscode +.idea diff --git a/.redocly.lint-ignore.yaml b/.redocly.lint-ignore.yaml new file mode 100644 index 00000000..e916a404 --- /dev/null +++ b/.redocly.lint-ignore.yaml @@ -0,0 +1,8 @@ +openapi.yaml: + no-required-schema-properties-undefined: + - '#/components/schemas/dimension_spatial_horizontal/allOf/1/required/0' + - '#/components/schemas/dimension_spatial_vertical/allOf/1/anyOf/0/required/0' + - '#/components/schemas/dimension_spatial_vertical/allOf/1/anyOf/1/required/0' + - '#/paths/~1jobs~1{job_id}~1estimate/get/responses/200/content/application~1json/schema/anyOf/0/required/0' + - '#/paths/~1jobs~1{job_id}~1estimate/get/responses/200/content/application~1json/schema/anyOf/1/required/0' + - '#/paths/~1jobs~1{job_id}~1estimate/get/responses/200/content/application~1json/schema/anyOf/2/required/0' diff --git a/.redocly.yaml b/.redocly.yaml new file mode 100644 index 00000000..7afe3dcc --- /dev/null +++ b/.redocly.yaml @@ -0,0 +1,16 @@ +extends: + - recommended + +openapi: + expandResponses: "200,201,202,203,204" + pathInMiddlePanel: true + +apis: + core: + root: ./openapi.yaml + commercial-data: + root: ./extensions/commercial-data/openapi.yaml + processing-parameters: + root: ./extensions/processing-parameters/openapi.yaml + workspaces: + root: ./extensions/workspaces/openapi.yaml \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f7636f0..b21b8395 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Fixed +- `GET /conformance`: Added missing security definitions - `GET /file_formats`: Base parameter on top of normal JSON Schema, not Process JSON Schema - `PATCH /services/{service_id}` and `PATCH /jobs/{job_id}`: Explicitly allow updating back-end specific properties (as in `POST`) - `GET /services/{service_id}` and `GET /jobs/{job_id}`: Explicitly allow listing back-end specific properties (as provided in `POST`) @@ -37,6 +38,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Clarified the behaviour of `federation:backends` for `POST /validation` - Clarified the meaning of `expires` in batch job results - Clarified that `last_successful_check` (from Federation Extension) can be null. +- Fixed various OpenAPI issues reported by redocly lint ## [1.2.0] - 2021-05-25 diff --git a/README.md b/README.md index f677fee1..a00d2f11 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,6 @@ For development some tools can be used: 1. Install [node and npm](https://nodejs.org) - should run with any recent version 2. Run `npm install` in this folder to install the dependencies -3. Run the linter for the OpenAPI file with `npm test`. This will lint the files and check against some best-practices. It uses `spectral` in the background. +3. Run the linter for the OpenAPI file with `npm test`. This will lint the files and check against some best-practices. It uses `spectral` and `redocly` in the background. 4. To show the files nicely formatted in a web browser, run `npm start`. It starts a server and opens the API specification rendered with ReDoc in a web browser. -5. To create a static HTML page (e.g. for hosting it on GitHub Pages), you can run `npm run build` and it will create a `redoc.html` in this folder. +5. To create a static HTML page (e.g. for hosting it on GitHub Pages), you can run `npm run build` and it will create a `index.html` in this folder and additional files for the extensions. diff --git a/extensions/commercial-data/.spectral.yml b/extensions/commercial-data/.spectral.yml deleted file mode 100644 index ad10553b..00000000 --- a/extensions/commercial-data/.spectral.yml +++ /dev/null @@ -1,12 +0,0 @@ -extends: "spectral:oas" -rules: - contact-properties: true - tag-description: true - oas3-parameter-description: true - oas3-unused-component: true - operation-id-kebab-case: - given: "$..operationId" - then: - function: pattern - functionOptions: - match: ^[a-z][a-z0-9\-]*$ \ No newline at end of file diff --git a/extensions/commercial-data/openapi.yaml b/extensions/commercial-data/openapi.yaml index bab5637d..8c5cd65f 100644 --- a/extensions/commercial-data/openapi.yaml +++ b/extensions/commercial-data/openapi.yaml @@ -159,11 +159,9 @@ paths: content: application/json: schema: + type: object allOf: - $ref: '#/components/schemas/order' - - type: object - required: - - items 4XX: $ref: '../../openapi.yaml#/components/responses/client_error_auth' 5XX: diff --git a/extensions/commercial-data/package.json b/extensions/commercial-data/package.json deleted file mode 100644 index 87e80dfa..00000000 --- a/extensions/commercial-data/package.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "name": "@openeo/api-extension-commercial-data", - "version": "0.1.0", - "author": "openEO Consortium", - "license": "Apache-2.0", - "description": "The openEO API specification.", - "homepage": "https://openeo.org", - "bugs": { - "url": "https://github.com/Open-EO/openeo-api/issues" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/Open-EO/openeo-api.git" - }, - "devDependencies": { - "@stoplight/spectral-cli": "^6.6.0", - "redoc-cli": "^0.13.21" - }, - "scripts": { - "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", - "build": "redoc-cli bundle openapi.yaml -o redoc.html --title \"openEO API - Commercial Data Extension\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", - "test": "spectral lint openapi.yaml" - } -} diff --git a/extensions/processing-parameters/.spectral.yml b/extensions/processing-parameters/.spectral.yml deleted file mode 100644 index ad10553b..00000000 --- a/extensions/processing-parameters/.spectral.yml +++ /dev/null @@ -1,12 +0,0 @@ -extends: "spectral:oas" -rules: - contact-properties: true - tag-description: true - oas3-parameter-description: true - oas3-unused-component: true - operation-id-kebab-case: - given: "$..operationId" - then: - function: pattern - functionOptions: - match: ^[a-z][a-z0-9\-]*$ \ No newline at end of file diff --git a/extensions/processing-parameters/openapi.yaml b/extensions/processing-parameters/openapi.yaml index 4b188266..85b974fb 100644 --- a/extensions/processing-parameters/openapi.yaml +++ b/extensions/processing-parameters/openapi.yaml @@ -77,6 +77,10 @@ paths: $ref: '#/components/schemas/processing_create_parameters' create_synchronous_parameters: $ref: '#/components/schemas/processing_create_parameters' + 4XX: + $ref: '../../openapi.yaml#/components/responses/client_error' + 5XX: + $ref: '../../openapi.yaml#/components/responses/server_error' components: schemas: processing_create_parameters: diff --git a/extensions/processing-parameters/package.json b/extensions/processing-parameters/package.json deleted file mode 100644 index 841560a5..00000000 --- a/extensions/processing-parameters/package.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "name": "@openeo/api-extension-processing-parameters", - "version": "0.1.0", - "author": "openEO Consortium", - "license": "Apache-2.0", - "description": "The openEO API specification.", - "homepage": "https://openeo.org", - "bugs": { - "url": "https://github.com/Open-EO/openeo-api/issues" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/Open-EO/openeo-api.git" - }, - "devDependencies": { - "@stoplight/spectral-cli": "^6.6.0", - "redoc-cli": "^0.13.21" - }, - "scripts": { - "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", - "build": "redoc-cli bundle openapi.yaml -o redoc.html --title \"openEO API - Processing Parameters Extension\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", - "test": "spectral lint openapi.yaml" - } -} diff --git a/extensions/workspaces/.spectral.yml b/extensions/workspaces/.spectral.yml deleted file mode 100644 index ad10553b..00000000 --- a/extensions/workspaces/.spectral.yml +++ /dev/null @@ -1,12 +0,0 @@ -extends: "spectral:oas" -rules: - contact-properties: true - tag-description: true - oas3-parameter-description: true - oas3-unused-component: true - operation-id-kebab-case: - given: "$..operationId" - then: - function: pattern - functionOptions: - match: ^[a-z][a-z0-9\-]*$ \ No newline at end of file diff --git a/extensions/workspaces/openapi.yaml b/extensions/workspaces/openapi.yaml index b4a72836..2b95d378 100644 --- a/extensions/workspaces/openapi.yaml +++ b/extensions/workspaces/openapi.yaml @@ -120,15 +120,19 @@ paths: - register parameters: aws_access_key_id: - title: AWS access key + description: AWS access key type: string aws_secret_access_key: - title: AWS secret key associated with the access key. + description: AWS secret key associated with the access key. type: string bucket_name: - title: Bucket name + description: Bucket name type: string - links: [] + links: [] + 4XX: + $ref: '../../openapi.yaml#/components/responses/client_error_auth' + 5XX: + $ref: '../../openapi.yaml#/components/responses/server_error' /workspaces: get: summary: List all workspaces @@ -202,7 +206,6 @@ paths: mapping: create: '#/components/schemas/create_workspace' register: '#/components/schemas/register_workspace' - required: true responses: '201': description: The workspace creation has been queued successfully. diff --git a/extensions/workspaces/package.json b/extensions/workspaces/package.json deleted file mode 100644 index 05b2a0f1..00000000 --- a/extensions/workspaces/package.json +++ /dev/null @@ -1,24 +0,0 @@ -{ - "name": "@openeo/api-extension-workspaces", - "version": "0.1.0", - "author": "openEO Consortium", - "license": "Apache-2.0", - "description": "The openEO API specification.", - "homepage": "https://openeo.org", - "bugs": { - "url": "https://github.com/Open-EO/openeo-api/issues" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/Open-EO/openeo-api.git" - }, - "devDependencies": { - "@stoplight/spectral-cli": "^6.6.0", - "redoc-cli": "^0.13.21" - }, - "scripts": { - "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", - "build": "redoc-cli bundle openapi.yaml -o redoc.html --title \"openEO API - Workspace Extension\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", - "test": "spectral lint openapi.yaml" - } -} diff --git a/openapi.yaml b/openapi.yaml index 7ed08b7c..1556db1a 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1209,6 +1209,9 @@ paths: - [OGC API standards](https://ogcapi.ogc.org/) tags: - Capabilities + security: + - {} + - Bearer: [] responses: '200': description: The URIs of all conformance classes supported by the server. @@ -1222,6 +1225,8 @@ paths: properties: conformsTo: $ref: '#/components/schemas/conformsTo' + 4XX: + $ref: '#/components/responses/client_error' 5XX: $ref: '#/components/responses/server_error' /collections: @@ -3962,12 +3967,13 @@ components: bbox: $ref: '#/components/schemas/bbox' geometry: + type: object + nullable: true description: |- Defines the full footprint of the asset represented by this item as GeoJSON Geometry. Results without a known location can set this value to `null`. - nullable: true allOf: - $ref: '#/components/schemas/GeoJsonGeometry' example: @@ -5057,7 +5063,6 @@ components: process_argument_value: title: Process Argument Value description: Arguments for a process. See the API documentation for more information. - nullable: true anyOf: - type: object nullable: true @@ -6114,6 +6119,9 @@ components: type: object required: - type + properties: + type: + type: string oneOf: - title: Spatial (raster) properties: @@ -6218,6 +6226,11 @@ components: additionalProperties: description: >- Any other property supported by the JSON Schema version that is given through the property `$schema` are allowed. Defaults to JSON Schema [draft-07](https://json-schema.org/draft-07/json-schema-validation.html), but can also be any later version of JSON Schema. + example: + type: string + enum: + - a + - b json_schema_type: type: string enum: @@ -6246,7 +6259,7 @@ components: Note: The pattern only specifies a minimal subset of invalid characters. The back-ends MAY enforce additional restrictions depending on their OS/environment. example: folder/file.txt - pattern: "^[^/\r\n\\:'\"][^\r\n\\:'\"]*$" + pattern: "^[^/\\r\\n\\t\\\\:'\"][^\\r\\n\\t\\\\:'\"]*$" size: type: integer description: File size in bytes. @@ -6289,42 +6302,6 @@ components: - Point coordinates: $ref: '#/components/schemas/GeoJsonPoint3D' - GeoJsonFeatureCollection: - type: object - required: - - type - - features - properties: - type: - type: string - enum: - - FeatureCollection - features: - type: array - items: - $ref: '#/components/schemas/GeoJsonFeature' - GeoJsonFeature: - type: object - required: - - type - - geometry - - properties - properties: - type: - type: string - enum: - - Feature - geometry: - $ref: '#/components/schemas/GeoJsonGeometry' - properties: - type: object - nullable: true - GeoJson: - title: GeoJSON - oneOf: - - $ref: '#/components/schemas/GeoJsonFeatureCollection' - - $ref: '#/components/schemas/GeoJsonFeature' - - $ref: '#/components/schemas/GeoJsonGeometry' GeoJsonGeometry: title: GeoJSON Geometry type: object diff --git a/package.json b/package.json index dbbb4094..69bd5937 100644 --- a/package.json +++ b/package.json @@ -13,12 +13,19 @@ "url": "git+https://github.com/Open-EO/openeo-api.git" }, "devDependencies": { - "@stoplight/spectral-cli": "^6.6.0", - "redoc-cli": "^0.13.21" + "@stoplight/spectral-cli": "^6.15.0", + "@redocly/cli": "^2.0.8", + "http-server": "^14.1.1" }, "scripts": { - "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", - "build": "redoc-cli build openapi.yaml -o redoc.html --title \"openEO API\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", - "test": "spectral lint openapi.yaml" + "start": "npm run build && http-server -o index.html", + "build": "npm run build:core && npm run build:commercial-data && npm run build:processing-parameters && npm run build:workspaces", + "build:core": "redocly build-docs core --config=.redocly.yaml -o=index.html", + "build:commercial-data": "redocly build-docs commercial-data --config=.redocly.yaml -o=commercial-data.html", + "build:processing-parameters": "redocly build-docs processing-parameters --config=.redocly.yaml -o=processing-parameters.html", + "build:workspaces": "redocly build-docs workspaces --config=.redocly.yaml -o=workspaces.html", + "test": "npm run spectral-lint && npm run redocly-lint", + "spectral-lint": "spectral lint openapi.yaml extensions/*/openapi.yaml", + "redocly-lint": "redocly lint --config=.redocly.yaml" } } From 5c8e12bcabedef3a30348fe88577fc753e733ed9 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 11 Sep 2025 18:19:55 +0200 Subject: [PATCH 45/52] `GET /credentials/oidc`: Added `authorization_parameters` property to enforce specific parameters for the authorization endpoint #534 (#570) --- CHANGELOG.md | 1 + openapi.yaml | 11 +++++++++++ 2 files changed, 12 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b21b8395..52fddd60 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **New extensions:** - [Remote Process Definition Extension](./extensions/remote-process-definition/README.md) - [Processing Parameters Extension](./extensions/processing-parameters/README.md) +- `GET /credentials/oidc`: Added `authorization_parameters` property to enforce specific parameters for the authorization endpoint [#534](https://github.com/Open-EO/openeo-api/issues/534) - `POST /result`: Added response header "OpenEO-Identifier" to expose an identifier associated with a synchronous processing request. - Added `version` property to `GET /processes` [#517](https://github.com/Open-EO/openeo-api/issues/517) - Added `queued`, `started` and `unpublished` to the batch job metadata and the corresponding STAC results [#542](https://github.com/Open-EO/openeo-api/issues/542) diff --git a/openapi.yaml b/openapi.yaml index 1556db1a..174bebc6 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2057,6 +2057,15 @@ paths: items: type: string format: uri + authorization_parameters: + type: object + description: |- + Additional parameters that an openEO client MUST include when requesting the authorization endpoint. + This can be used to enforce specific + [request parameters such as `prompt`](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). + example: + prompt: consent + access_type: offline links: type: array description: |- @@ -2095,6 +2104,8 @@ paths: - profile - email - earthengine + authorization_parameters: + access_type: offline - id: ms issuer: 'https://login.microsoftonline.com/example-tenant/v2.0' title: Microsoft From 8b63b586888c216ef6025df8d7db1d5dc9af90cc Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 18 Sep 2025 18:24:02 +0200 Subject: [PATCH 46/52] Added a status diagram that explains the status changes of batch jobs #436 (#573) --- CHANGELOG.md | 1 + assets/status-diagram.png | Bin 0 -> 23267 bytes openapi.yaml | 7 ++++++- 3 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 assets/status-diagram.png diff --git a/CHANGELOG.md b/CHANGELOG.md index 52fddd60..7d79674d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added `version` property to `GET /processes` [#517](https://github.com/Open-EO/openeo-api/issues/517) - Added `queued`, `started` and `unpublished` to the batch job metadata and the corresponding STAC results [#542](https://github.com/Open-EO/openeo-api/issues/542) - Added all the batch job timestamps (including the new timestamps above) to the Collection type of batch job results +- Added a status diagram that explains the status changes of batch jobs [#436](https://github.com/Open-EO/openeo-api/issues/436) ### Deprecated diff --git a/assets/status-diagram.png b/assets/status-diagram.png new file mode 100644 index 0000000000000000000000000000000000000000..9ca6daabc2a34d768f887d899709f2b2054fd609 GIT binary patch literal 23267 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 O+f99w8|AQnU;GE#3u>bP literal 0 HcmV?d00001 diff --git a/openapi.yaml b/openapi.yaml index 174bebc6..0a342035 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -5608,6 +5608,7 @@ components: The current status of a batch job. The following status changes can occur: + * `POST /jobs`: The status is initialized as `created`. * `POST /jobs/{job_id}/results`: The status is set to `queued`, if processing does not start instantly. @@ -5617,7 +5618,11 @@ components: * `DELETE /jobs/{job_id}/results`: The 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`. + `created`. + + The following state diagram shows the possible status changes: + + ![State diagram](assets/status-diagram.png) example: running default: created progress: From a2a80cbd2f47b420de3b47202bea1eda6f8f9d7c Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 3 Oct 2025 13:35:31 +0100 Subject: [PATCH 47/52] Added `stacktrace` to log entries, e.g. for `GET /jobs/{job_id}/logs`) #512 (#571) --- CHANGELOG.md | 1 + openapi.yaml | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d79674d..f2a21da1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - [Processing Parameters Extension](./extensions/processing-parameters/README.md) - `GET /credentials/oidc`: Added `authorization_parameters` property to enforce specific parameters for the authorization endpoint [#534](https://github.com/Open-EO/openeo-api/issues/534) - `POST /result`: Added response header "OpenEO-Identifier" to expose an identifier associated with a synchronous processing request. +- Added `stacktrace` to log entries (e.g. for `GET /jobs/{job_id}/logs`) [#512](https://github.com/Open-EO/openeo-api/issues/512) - Added `version` property to `GET /processes` [#517](https://github.com/Open-EO/openeo-api/issues/517) - Added `queued`, `started` and `unpublished` to the batch job metadata and the corresponding STAC results [#542](https://github.com/Open-EO/openeo-api/issues/542) - Added all the batch job timestamps (including the new timestamps above) to the Collection type of batch job results diff --git a/openapi.yaml b/openapi.yaml index 0a342035..446dd776 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -6491,6 +6491,10 @@ components: example: udf usage: $ref: '#/components/schemas/usage' + stacktrace: + type: string + description: >- + A stacktrace or similar, may include whitespaces for formatting. links: $ref: '#/components/schemas/log_links' usage: From 6a62ff801a482db98f0e95ae75c9102250c93c58 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 6 Oct 2025 13:54:24 +0200 Subject: [PATCH 48/52] Clarifies the terms "end"/"result" nodes and "root"/"child" process graphs (#572) * Clarified the relation between "result nodes" and "end nodes", the usage of the `result` flag, and the relation between the outermost ("root") and "child" process graphs #547 * Update openapi.yaml Co-authored-by: Stefaan Lippens --------- Co-authored-by: Stefaan Lippens --- CHANGELOG.md | 1 + openapi.yaml | 10 +++++++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f2a21da1..3d403279 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Clarified the behaviour of `federation:backends` for `POST /validation` - Clarified the meaning of `expires` in batch job results - Clarified that `last_successful_check` (from Federation Extension) can be null. +- Clarified the relation between result and end nodes, the usage of the result flag, and the relation between the outermost ("root") and child process graphs [#547](https://github.com/Open-EO/openeo-api/issues/547) - Fixed various OpenAPI issues reported by redocly lint ## [1.2.0] - 2021-05-25 diff --git a/openapi.yaml b/openapi.yaml index 446dd776..d65ac7b5 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -323,10 +323,14 @@ info: ``` A process node MUST always contain key-value-pairs named `process_id` and `arguments`. It MAY contain a `description`. - One of the nodes in a map of processes (the final one) MUST have the `result` flag set to `true`, all the other nodes can omit it as the default value is `false`. Having such a node is important as multiple end nodes are possible, but in most use cases it is important to exactly specify the return value to be used by other processes. Each child process graph must also specify a result node similar to the "main" process graph. - `process_id` MUST be a valid process ID in the `namespace` given. Clients SHOULD warn the user if a user-defined process is added with the same identifier as one of the predefined process. + In the following, "end node" (also known as "leaf node") defines a node that is not referenced by any other node in the same process graph. The "root process graph" is the outermost process graph, which is not part of any other process graph. + + A "result node" is a node (often an end node, but that's not required) that defines the return value of the process graph and has the `result` flag set to `true`. Exactly one of the nodes in a map of processes MUST have the `result` flag set to `true`, all the other nodes can omit it as the default value is `false`. Each child process graph MUST specify its own result node. The root process graph MUST also specify a result node although not strictly needed in all use cases. + + Having a result node is important as multiple end nodes are possible and in many use cases it is important to identify a specific return value for the process graph that is passed to other processes. The result node is not necessarily an end node. + ### Arguments A process can have an arbitrary number of arguments. Their name and value are specified @@ -437,7 +441,7 @@ info: ### Full example for an EVI computation - Deriving minimum EVI (Enhanced Vegetation Index) measurements over pixel time series of Sentinel-2 imagery. The main process graph in blue, child process graphs in yellow: + Deriving minimum EVI (Enhanced Vegetation Index) measurements over pixel time series of Sentinel-2 imagery. The root process graph in blue, child process graphs in yellow: ![Graph with processing instructions](assets/pg-evi-example.png) From 7483918656bc10692ce8fa9b5994dbaf2e3069be Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 21 Oct 2025 17:09:41 +0200 Subject: [PATCH 49/52] Add web-editor relation type #577 (#578) --- CHANGELOG.md | 1 + openapi.yaml | 10 ++++++++++ 2 files changed, 11 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d403279..3f8e5fab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **New extensions:** - [Remote Process Definition Extension](./extensions/remote-process-definition/README.md) - [Processing Parameters Extension](./extensions/processing-parameters/README.md) +- `GET /`: New relation type `web-editor` [#577](https://github.com/Open-EO/openeo-api/issues/577) - `GET /credentials/oidc`: Added `authorization_parameters` property to enforce specific parameters for the authorization endpoint [#534](https://github.com/Open-EO/openeo-api/issues/534) - `POST /result`: Added response header "OpenEO-Identifier" to expose an identifier associated with a synchronous processing request. - Added `stacktrace` to log entries (e.g. for `GET /jobs/{job_id}/logs`) [#512](https://github.com/Open-EO/openeo-api/issues/512) diff --git a/openapi.yaml b/openapi.yaml index d65ac7b5..1052c73c 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -882,6 +882,11 @@ paths: recover a user account (e.g. to reset the password or send a reminder about the username to the user's email account). + 9. `web-editor`: A link to an openEO Web Editor instance. + This allows clients to open a Web Editor for other tasks. + It may be accompanied with a `version` flag in the link + to allow feature-detection for certain Web Editor functionalities. + For additional relation types see also the lists of [common relation types in openEO](#section/API-Principles/Web-Linking). type: array @@ -920,6 +925,11 @@ paths: rel: data type: application/json title: List of Datasets + - href: 'https://editor.openeo.org' + rel: web-editor + type: text/html + title: openEO Web Editor + version: '0.14.0' 4XX: $ref: '#/components/responses/client_error' 5XX: From 5f6aab6ba94c628e7c535c0e4027d7da2d430658 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 28 Oct 2025 18:53:10 +0100 Subject: [PATCH 50/52] Migrate from openEO-specific tokens to JWT #558 (#567) * Migrate from openEO-specific tokens to JWT #558 Co-authored-by: Stefaan Lippens --- CHANGELOG.md | 11 +++++- openapi.yaml | 94 ++++++++++++++++++++++++++++++---------------------- 2 files changed, 65 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3f8e5fab..f3fc90e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,8 +17,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Added `stacktrace` to log entries (e.g. for `GET /jobs/{job_id}/logs`) [#512](https://github.com/Open-EO/openeo-api/issues/512) - Added `version` property to `GET /processes` [#517](https://github.com/Open-EO/openeo-api/issues/517) - Added `queued`, `started` and `unpublished` to the batch job metadata and the corresponding STAC results [#542](https://github.com/Open-EO/openeo-api/issues/542) -- Added all the batch job timestamps (including the new timestamps above) to the Collection type of batch job results - Added a status diagram that explains the status changes of batch jobs [#436](https://github.com/Open-EO/openeo-api/issues/436) +- Added all the batch job timestamps (including the new timestamps above) to the Collection type of batch job results +- Support for standard JSON Web Tokens (JWT) being used as Bearer tokens [#558](https://github.com/Open-EO/openeo-api/issues/558) + +### Deprecated + +- Deprecated the openEO-specific Bearer token format (authentication mechanism/provider id/access token) [#558](https://github.com/Open-EO/openeo-api/issues/558) + +### Changed + +- Migrate from openEO-specific tokens to JWT, i.e. deprecating the openEO-specific format in favor of JWT [#558](https://github.com/Open-EO/openeo-api/issues/558) ### Deprecated diff --git a/openapi.yaml b/openapi.yaml index 1052c73c..768e5bff 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1909,18 +1909,7 @@ paths: openEO clients MUST use the **access token** as part of the Bearer token for authorization in subsequent API calls (see also the information about Bearer tokens in this document). Clients MUST NOT use the id token - or the authorization code. The access token provided by an OpenID Connect - Provider does not necessarily provide information about the issuer (i.e. the - OpenID Connect provider) and therefore a prefix MUST be added to the Bearer - Token sent in subsequent API calls to protected endpoints. The Bearer - Token sent to protected endpoints MUST consist of the authentication - method (here `oidc`), the provider ID and the access token itself. All - separated by a forward slash `/`. The provider ID corresponds to the - value specified for `id` for each provider in the response body of this - endpoint. The header in subsequent API calls for a provider with `id` - `ms` would look as follows: `Authorization: Bearer oidc/ms/TOKEN` - (replace `TOKEN` with the actual access token received from the OpenID - Connect Provider). + or the authorization code. Back-ends MAY request user information ([including Claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims)) from the [OpenID Connect Userinfo endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) @@ -1959,14 +1948,15 @@ paths: properties: id: type: string - description: >- - A per-back-end **unique** identifier for the OpenID Connect Provider to - be as prefix for the Bearer token. + description: |- + A per-back-end **unique** identifier for the OpenID Connect provider. + + Is used as prefix for the openEO token. pattern: '[\d\w]{1,20}' issuer: type: string format: uri - description: >- + description: |- The [issuer location](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig) (also referred to as 'authority' in some client libraries) is the URL of the OpenID Connect provider, which conforms to a set of rules: @@ -1980,7 +1970,6 @@ paths: OpenID Connect. 2. The URL MUST NOT contain a terminating forward slash `/`. - example: 'https://accounts.google.com' scopes: type: array @@ -2133,11 +2122,10 @@ paths: get: summary: HTTP Basic authentication operationId: authenticate-basic - description: >- + description: |- Checks the credentials provided through [HTTP Basic Authentication - according to RFC 7617](https://www.rfc-editor.org/rfc/rfc7617.html) and returns - an access token for valid credentials. - + according to RFC 7617](https://www.rfc-editor.org/rfc/rfc7617.html) and + returns an access token in exchange for providing valid credentials. The credentials (username and password) MUST be sent in the HTTP header `Authorization` with type `Basic` and the Base64 encoded string @@ -2145,15 +2133,9 @@ paths: header would look as follows for username `user` and password `pw`: `Authorization: Basic dXNlcjpwdw==`. - The access token has to be used in the Bearer token for authorization in subsequent API calls (see also the information about Bearer tokens in - this document). The access token returned by this request MUST NOT be - provided with `basic//` prefix, but the Bearer Token sent in subsequent - API calls to protected endpoints MUST be prefixed with `basic//`. The - header in subsequent API calls would look as follows: `Authorization: - Bearer basic//TOKEN` (replace `TOKEN` with the actual access token). - + this document). It is RECOMMENDED to implement this authentication method for non-public services only. @@ -2174,9 +2156,8 @@ paths: properties: access_token: description: >- - The access token (without `basic//` prefix) to be used in - the Bearer token for authorization in subsequent API - calls. + The access token to be used in the Bearer token for authorization + in subsequent API calls (without the custom `basic//` prefix). type: string example: b34ba2bdf9ac9ee1 4XX: @@ -6820,14 +6801,49 @@ components: Bearer: type: http scheme: bearer - bearerFormat: >- - The Bearer Token MUST consist of the authentication method, a provider - ID (if available) and the token itself. All separated by a forward slash - `/`. Examples (replace `TOKEN` with the actual access token): (1) Basic - authentication (no provider ID available): `basic//TOKEN` (2) OpenID - Connect (provider ID is `ms`): `oidc/ms/TOKEN`. For OpenID Connect, the - provider ID corresponds to the value specified for `id` for each - provider in `GET /credentials/oidc`. + bearerFormat: JWT or openEO + description: >- + A Bearer token can be provided in two different formats: + + 1. **JSON Web Token (JWT) - RECOMMENDED** + + - Conformance class: `https://api.openeo.org/1.2.0/authentication/jwt` + + The Bearer token is an access token in [JWT](https://datatracker.ietf.org/doc/html/rfc7519) format + as defined in RFC 7519. For openEO, it MUST include the issuer in the + `iss` claim although being optional in RFC 7519. + If the concept of an issuer does not exist in an authentication method (e.g. in HTTP Basic), + implementations could use the endpoint for Basic Authentication as the issuer, for example. + + openEO backend implementations MUST signal their support for JWT by listing the given + conformance class. Likewise, openEO clients SHOULD only use JWT when the openEO backend + lists the conformance class. + + 2. **openEO Tokens - DEPRECATED** + + - Conformance class: *None* + + The Bearer Token is constructed from the authentication method, a + provider ID (if available) and the access token. All separated by a + forward slash `/`. + + Examples (replace `TOKEN` with the actual access token): + + - Basic authentication (no provider ID available): `basic//TOKEN` + - OpenID Connect (provider ID is `ms`): `oidc/ms/TOKEN`. + For OpenID Connect, the provider ID corresponds to the value + specified for `id` for each provider in `GET /credentials/oidc`. + + All openEO backends MUST accept this method for backward compatibility + until version 2.0 of the specification. + + The access tokens provided by the identity provider do not include + the prefix that includes the authentication method and provider ID. + The Bearer Token sent to the openEO backend MUST have the prefix, e.g. `basic//` for Basic authentication. + This means that the clients have to prepend the prefix. + + JWT and openEO tokens can be distinguished by the presence of a slash + `/` in the token, which JWT can never contain due to the Base64 encoding. Basic: type: http scheme: basic From 388231c12ee6d09a2cca4a16be5264aa316af677 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 7 Jan 2026 17:29:22 +0100 Subject: [PATCH 51/52] v1.3.0 release + extensions --- CHANGELOG.md | 23 +++++++++++++++-------- README.md | 8 +++++--- extensions/federation/README.md | 6 +++--- extensions/workspaces/README.md | 2 +- openapi.yaml | 22 +++++++++++----------- package.json | 2 +- 6 files changed, 36 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f3fc90e3..58a54c51 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,13 +4,24 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## Unreleased / Draft +## [Unreleased] / Draft + +### Added + +### Deprecated + +### Changed + +### Fixed + +## [1.3.0] - 2026-02-02 ### Added - **New extensions:** - [Remote Process Definition Extension](./extensions/remote-process-definition/README.md) - [Processing Parameters Extension](./extensions/processing-parameters/README.md) + - [Workspaces Extension](./extensions/workspaces/README.md) - `GET /`: New relation type `web-editor` [#577](https://github.com/Open-EO/openeo-api/issues/577) - `GET /credentials/oidc`: Added `authorization_parameters` property to enforce specific parameters for the authorization endpoint [#534](https://github.com/Open-EO/openeo-api/issues/534) - `POST /result`: Added response header "OpenEO-Identifier" to expose an identifier associated with a synchronous processing request. @@ -24,17 +35,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Deprecated - Deprecated the openEO-specific Bearer token format (authentication mechanism/provider id/access token) [#558](https://github.com/Open-EO/openeo-api/issues/558) - -### Changed - -- Migrate from openEO-specific tokens to JWT, i.e. deprecating the openEO-specific format in favor of JWT [#558](https://github.com/Open-EO/openeo-api/issues/558) - -### Deprecated - - STAC 0.9.x ### Changed +- Updated Federation Extension to v0.2.0 +- Migrate from openEO-specific tokens to JWT, i.e. deprecating the openEO-specific format in favor of JWT [#558](https://github.com/Open-EO/openeo-api/issues/558) - `GET /`: Requires the fields `type` and `conformsTo` - `GET /udf_runtimes`: Requires at least one UDF runtime to be provided. [#511](https://github.com/Open-EO/openeo-api/issues/511) @@ -479,6 +485,7 @@ Initial version. [Unreleased]: +[1.3.0]: [1.2.0]: [1.1.0]: [1.0.1]: diff --git a/README.md b/README.md index a00d2f11..e2e543d9 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,13 @@ openEO develops an open API to connect R, Python and JavaScript clients to big E ## Versions / Branches -The [master branch](https://github.com/Open-EO/openeo-api/tree/master) is the 'stable' version of the openEO API specification. It is currently version **1.2.0** of the specification. The [draft branch](https://github.com/Open-EO/openeo-api/tree/draft) is where active development takes place. +The [master branch](https://github.com/Open-EO/openeo-api/tree/master) is the 'stable' version of the openEO API specification. It is currently version **1.3.0** of the specification. The [draft branch](https://github.com/Open-EO/openeo-api/tree/draft) is where active development takes place. | Version / Branch | Status | Description | | --------------------------------------------------------- | ----------- | ----------- | | [draft](https://api.openeo.org/draft) | planned | *Unstable* - Next version. | -| [**1.2.0**](https://api.openeo.org) | **current** | Clarifications, new extensions, vector data cubes, STAC (API) updates, more link relation types, improved batch job results and logs. [Changelog](CHANGELOG.md#120---2023-05-31). | +| [**1.3.0**](https://api.openeo.org) | **current** | Clarifications, Remote Process Definition and Processing Parameters extensions, new token format, batch job improvements, etc. [Changelog](CHANGELOG.md#130---2026-02-02). | +| [1.2.0](https://api.openeo.org/1.2.0) | legacy | Clarifications, Commercial Data and Federation extensions, vector data cubes, STAC (API) updates, more link relation types, improved batch job results and logs. [Changelog](CHANGELOG.md#120---2023-05-31). | | [1.1.0](https://api.openeo.org/1.1.0) | legacy | Clarifications, STAC updates, return value for child processes, more details for logs and jobs, default clients for OIDC. [Changelog](CHANGELOG.md#110---2021-06-15). | | [1.0.1](https://api.openeo.org/1.0.1) | legacy | Clarifications, bugfixes and CORS improvements. [Changelog](CHANGELOG.md#101---2020-12-07). | | [1.0.0](https://api.openeo.org/1.0.0) | legacy | First stable version of openEO. [Changelog](CHANGELOG.md#100---2020-07-17). | @@ -32,9 +33,10 @@ See also the [changelog](CHANGELOG.md) and the [milestones](https://github.com/O | Name | Version | Stability | Description | | ------------------------------------------------------------------ | ------- | ------------ | ----------- | | [Commercial Data](extensions/commercial-data/) | 0.1.0 | experimental | Provides an interface for discovering, ordering and using commercial data. | -| [Federation](extensions/federation/) | 0.1.0 | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. | +| [Federation](extensions/federation/) | 0.2.0 | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. | | [Processing Parameters](extensions/processing-parameters/) | 0.1.0 | experimental | Explore and handle additional processing parameters that a back-end can offer for the processing modes (sync. processing, batch jobs, web services). | | [Remote Process Definition](extensions/remote-process-definition/) | 0.1.0 | experimental | Load user-defined processes that are hosted externally through the process namespace into process graphs. | +| [Workspaces](extensions/workspaces/) | 0.1.0 | experimental | Connect external file storage systems (e.g. cloud buckets) to openEO back-end implementations. | ## Repository diff --git a/extensions/federation/README.md b/extensions/federation/README.md index 02253179..4ea3bda5 100644 --- a/extensions/federation/README.md +++ b/extensions/federation/README.md @@ -4,9 +4,9 @@ The openEO API is a specification for interoperable cloud-based processing of la This is an extension for federation aspects, i.e. where multiple back-ends are exposed as a single API. -- Version: **0.1.0** +- Version: **0.2.0** - Stability: **experimental** -- Conformance class: `https://api.openeo.org/extensions/federation/0.1.0` +- Conformance class: `https://api.openeo.org/extensions/federation/0.2.0` **Note:** This document only documents the additions to the specification. Extensions can not change or break existing behavior of the openEO API. @@ -84,7 +84,7 @@ schema: ```json { - "api_version": "1.2.0", + "api_version": "1.3.0", "federation": { "vito": { "title": "VITO", diff --git a/extensions/workspaces/README.md b/extensions/workspaces/README.md index 1d1be677..d512830a 100644 --- a/extensions/workspaces/README.md +++ b/extensions/workspaces/README.md @@ -10,4 +10,4 @@ The Workspace Extension to the openEO API provides an interface for connecting e **Note:** This document only documents the additions to the specification. Extensions can not change or break existing behavior of the openEO API. -The Workspace API is inspired by the [EOEPCA Workspace API](https://github.com/EOEPCA/rm-workspace-api) with regards to workspace management. \ No newline at end of file +The Workspace API is inspired by the [EOEPCA Workspace API](https://github.com/EOEPCA/rm-workspace-api) with regards to workspace management. diff --git a/openapi.yaml b/openapi.yaml index 768e5bff..cb66993d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -1,11 +1,11 @@ openapi: 3.0.2 info: title: openEO API - version: 1.2.0 + version: 1.3.0 description: |- The openEO API specification for interoperable cloud-based processing of large Earth observation datasets. - **Conformance class:** `https://api.openeo.org/1.2.0` + **Conformance class:** `https://api.openeo.org/1.3.0` # API Principles @@ -629,7 +629,7 @@ paths: Version number of the openEO API specification the back-end implements. enum: - - 1.2.0 + - 1.3.0 backend_version: type: string description: >- @@ -1029,9 +1029,9 @@ paths: example: versions: - url: 'https://openeo.example/api/v0' - api_version: 0.5.1 + api_version: 0.4.2 - url: 'https://openeo.example/api/v1' - api_version: 1.2.0 + api_version: 1.3.0 - url: 'https://dev.openeo.example/api/v2' production: false api_version: 2.0.0-beta @@ -1212,7 +1212,7 @@ paths: Otherwise, the implemented functionality can usually be retrieved from the [capabilities](#tag/Capabilities/operation/capabilities) in openEO. - The general openEO conformance class is `https://api.openeo.org/1.2.0`. + The general openEO conformance class is `https://api.openeo.org/1.3.0`. See the individual openEO API extensions for their conformance classes. The conformance classes listed at this endpoint and listed in the @@ -1694,7 +1694,7 @@ paths: Clients must be able to handle multiple process specification versions at the same time. This is **not** the openEO API specification version. - example: 1.2.0 + example: 2.0.0 processes: type: array items: @@ -3776,16 +3776,16 @@ components: implementation conforms to. Conformance classes are commonly used in all OGC API standards and the STAC API specification. - The general openEO conformance class is `https://api.openeo.org/1.2.0`. + The general openEO conformance class is `https://api.openeo.org/1.3.0`. See the individual openEO API extensions for their conformance classes. type: array items: type: string format: uri example: - - https://api.openeo.org/1.2.0 + - https://api.openeo.org/1.3.0 - https://api.openeo.org/extensions/commercial-data/0.1.0 - - https://api.openeo.org/extensions/federation/0.1.0 + - https://api.openeo.org/extensions/federation/0.2.0 - https://api.stacspec.org/v1.0.0/core - https://api.stacspec.org/v1.0.0/collections udf_runtime: @@ -6807,7 +6807,7 @@ components: 1. **JSON Web Token (JWT) - RECOMMENDED** - - Conformance class: `https://api.openeo.org/1.2.0/authentication/jwt` + - Conformance class: `https://api.openeo.org/1.3.0/authentication/jwt` The Bearer token is an access token in [JWT](https://datatracker.ietf.org/doc/html/rfc7519) format as defined in RFC 7519. For openEO, it MUST include the issuer in the diff --git a/package.json b/package.json index 69bd5937..3502ae70 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@openeo/api", - "version": "1.2.0", + "version": "1.3.0", "author": "openEO Consortium", "license": "Apache-2.0", "description": "The openEO API specification.", From a2efa3464c28242e98d72973db09f7eda9767583 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 8 Jan 2026 10:43:31 +0100 Subject: [PATCH 52/52] Improve wording #582 --- errors.json | 4 ++-- openapi.yaml | 14 +++++++------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/errors.json b/errors.json index 7e23b496..ac430b16 100644 --- a/errors.json +++ b/errors.json @@ -241,8 +241,8 @@ ] }, "ProcessGraphComplexity": { - "description": "The process graph is computationally too heavy for synchronous processing and will likely time out. Please use a batch job instead.", - "message": "The process graph is too heavy for synchronous processing. Please use a batch job instead.", + "description": "The process graph is computationally too demanding for synchronous processing and will likely time out. Please use a batch job instead.", + "message": "The process graph is too demanding for synchronous processing. Please use a batch job instead.", "http": 400, "tags": [ "Data Processing" diff --git a/openapi.yaml b/openapi.yaml index cb66993d..d880c613 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -4030,7 +4030,7 @@ components: format: date-time description: >- For time series: The last or end date and time for the data, in - UTC. Formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) + UTC. Formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. title: $ref: '#/components/schemas/eo_title' @@ -5708,14 +5708,14 @@ components: format: date-time description: >- Date and time of creation (for batch jobs: the status 'created' was set), - formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. example: '2017-01-01T09:32:12Z' updated: type: string format: date-time description: >- Date and time of the last status change, - formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. If the status is `error`, `canceled` or `finished`, this is the time when the job has ended. example: '2017-01-01T09:54:18Z' @@ -5724,14 +5724,14 @@ components: format: date-time description: >- Date and time of queueing the batch job (i.e., when the status 'queued' was set), - formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. example: '2017-01-01T09:34:00Z' started: type: string format: date-time description: >- Date and time when the batch job started processing (i.e., when the status 'running' was set), - formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. example: '2017-01-01T09:36:18Z' expires: type: string @@ -5739,7 +5739,7 @@ components: description: >- Time in UTC until which the assets and this document are accessible via the signed URL that is provided with the relation type `canonical` in the links. - Formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + Formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. After expiration, a document with new signed URLs can be retrieved through an authenticated request to this endpoint. example: '2017-02-01T09:54:18Z' @@ -5748,7 +5748,7 @@ components: format: date-time description: >- Time until which the batch job results are stored on the back-end, in UTC. - Formatted as an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. + Formatted as a [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. example: '2018-01-01T09:54:18Z' description: type: string