diff --git a/.travis.yml b/.travis.yml index 0f46a297..b8618ead 100644 --- a/.travis.yml +++ b/.travis.yml @@ -13,7 +13,7 @@ before_install: - pip install mkdocs-macros-plugin - pip install pymdown-extensions - pip install pygments -- npm install -g asyncapi-generator +- npm install -g asyncapi-generator@0.6.7 # 0.7 only supports AsyncAPI 2.0 - npm install -g concat-json-files - npm install -g speccy - speccy lint openapi.json -r "speccy.yml" diff --git a/CHANGELOG.md b/CHANGELOG.md index f1b1d1fa..8a18080b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,26 @@ 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). +## [0.4.1] - 2019-05-29 + +### Changed +- Updated the process catalog, see the separate changelog. + +### Removed +- The property `sar:absolute_orbit` in `GET /collections/{collection_id}` has been removed. +- Sending a Bearer token to `GET /credentials/oidc` is not allowed any longer. + +### Fixed +- Improved and clarified the documentation and descriptions. +- `GET /collections/{collection_id}`: + - `properties` in `GET /collections/{collection_id}` doesn't require any of the integrated STAC extensions any longer. + - The property `sci:publications` in `GET /collections/{collection_id}` was ported over incorrectly from STAC. The data type has been changed from object to array. +- `GET /jobs/{job_id}/results` was expected to return HTTP status code 424 with an error message, but it was specified in `/jobs/{job_id}/estimate` instead. The definition was moved. [#177](https://github.com/Open-EO/openeo-api/issues/177) +- `path` in `GET` and `PUT` `/files/{user_id}` is required again. +- Fixed several issues in the client development guidelines. + ## [0.4.0] - 2019-03-07 + ### Added - `GET /jobs/{job_id}/estimate` can return the estimated required storage capacity. [#122](https://github.com/Open-EO/openeo-api/issues/122) - `GET /jobs/{job_id}` has two new properties: @@ -23,7 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Processes and parameters can be declared to be `experimental`. - `GET /output_formats` and `GET /service_types` can now provide links per entry. - `GET /udf_runtimes` provide a list of UDF runtime environments. [#87](https://github.com/Open-EO/openeo-api/issues/87) -- `GET /service_types` allows to specify `variables` that can be used in process graphs. [#172](https://github.com/Open-EO/openeo-api/issues/172) +- `GET /service_types` allows to specify `variables` that can be used in process graphs. [#172](https://github.com/Open-EO/openeo-api/issues/172) ### Changed - Completely new version of the processes. diff --git a/README.md b/README.md index c626c806..2f616b04 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ openEO develops an open API to connect R, python and javascript clients to big Earth observation cloud back-ends in a simple and unified way. This repository contains this API, the openEO (core) API. -* **[Documentation / Specification](https://open-eo.github.io/openeo-api/v/0.4.0/index.html)** +* **[Documentation / Specification](https://open-eo.github.io/openeo-api/v/0.4.1/index.html)** ## Versions -The openEO (core) API is currently released in version **0.4.0**. +The openEO (core) API is currently released in version **0.4.1**. **Note:** The specification is currently still an early version, with the potential for some major things to change. The core is now fleshed out, so implementors are encouraged to try it out and give feedback. But the goal is to actually be able to act on that feedback, which will mean changes are quite possible. A solid basis is specified right now, but best practices, extensions and specification details will emerge with implementation. @@ -16,8 +16,8 @@ The openEO (core) API is currently released in version **0.4.0**. | [0.0.2](https://github.com/Open-EO/openeo-api/tree/0.0.2) ([Spec](https://open-eo.github.io/openeo-api/v/0.0.2/index.html)) | legacy | Proof of concept, implemented. | | [0.3.0](https://github.com/Open-EO/openeo-api/tree/0.3.0) ([Spec](https://open-eo.github.io/openeo-api/v/0.3.0/index.html)) | legacy | Major rework. | | [0.3.1](https://github.com/Open-EO/openeo-api/tree/0.3.1) ([Spec](https://open-eo.github.io/openeo-api/v/0.3.1/index.html)) | legacy, supported | Fixing minor issues, see the [changelog](CHANGELOG.md#031---2018-11-06). | -| [**0.4.0**](https://github.com/Open-EO/openeo-api/tree/0.4.0) ([Spec](https://open-eo.github.io/openeo-api/v/0.4.0/index.html)) | **current** | Improved discovery, added processes catalogue, new process graph structure and [more](CHANGELOG.md#040---2019-03-07). | -| [0.4.1](https://github.com/Open-EO/openeo-api/tree/0.4.1) ([Spec](https://open-eo.github.io/openeo-api/v/0.4.1/index.html)) | draft | Bugfix release, see the [changelog](CHANGELOG.md). | +| [0.4.0](https://github.com/Open-EO/openeo-api/tree/0.4.0) ([Spec](https://open-eo.github.io/openeo-api/v/0.4.0/index.html)) | legacy, supported | Improved discovery, added processes catalogue, new process graph structure and [more](CHANGELOG.md#040---2019-03-07). | +| [**0.4.1**](https://github.com/Open-EO/openeo-api/tree/0.4.1) ([Spec](https://open-eo.github.io/openeo-api/v/0.4.1/index.html)) | **current** | Bugfix release, see the [changelog](CHANGELOG.md#041---2019-05-29). | | [0.5.0](https://github.com/Open-EO/openeo-api/tree/0.5.0) ([Spec](https://open-eo.github.io/openeo-api/v/0.5.0/index.html)) | planned | Improvements based on implementer feedback, introduce extension concept. | See also the [changelog](CHANGELOG.md) and the [milestones](https://github.com/Open-EO/openeo-api/milestones) for a rough roadmap based on GitHub issues. @@ -26,8 +26,8 @@ See also the [changelog](CHANGELOG.md) and the [milestones](https://github.com/O This repository contains a set of files formally and technically describing the openEO API, each with a human-readable and easily browseable version: -* [docs/](docs/) ([browseable version](https://open-eo.github.io/openeo-api/v/0.4.0/)) contains all additional written documentation, including 'getting started' guides, the architecture, feature descriptions, development guidelines and more. -* [processes/](processes/) ([browseable version](https://open-eo.github.io/openeo-api/v/0.4.0/processreference/)) defines pre-defined core processes back-ends may implement for best interoperability. -* [openapi.json](openapi.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.4.0/apireference/)) provides the [openAPI](https://www.openapis.org/) 3.0 definition of the openEO API. -* [subscriptions.json](subscriptions.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.4.0/apireference-subscriptions/)) provides the [AsyncAPI](https://www.asyncapi.com/) 1.2 definitions for the WebSocket-based subscriptions and notifications API for openEO. -* [errors.json](errors.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.4.0/errors/#openeo-error-codes)) is a list of potential global error codes and messages, excluding specific exceptions separately available for each process. +* [docs/](docs/) ([browseable version](https://open-eo.github.io/openeo-api/v/0.4.1/)) contains all additional written documentation, including 'getting started' guides, the architecture, feature descriptions, development guidelines and more. +* [processes/](processes/) ([browseable version](https://open-eo.github.io/openeo-api/v/0.4.1/processreference/)) defines pre-defined core processes back-ends may implement for best interoperability. +* [openapi.json](openapi.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.4.1/apireference/)) provides the [openAPI](https://www.openapis.org/) 3.0 definition of the openEO API. +* [subscriptions.json](subscriptions.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.4.1/apireference-subscriptions/)) provides the [AsyncAPI](https://www.asyncapi.com/) 1.2 definitions for the WebSocket-based subscriptions and notifications API for openEO. +* [errors.json](errors.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.4.1/errors/#openeo-error-codes)) is a list of potential global error codes and messages, excluding specific exceptions separately available for each process. diff --git a/docs/guidelines-clients.md b/docs/guidelines-clients.md index 54fafe3f..304bb4f5 100644 --- a/docs/guidelines-clients.md +++ b/docs/guidelines-clients.md @@ -91,7 +91,7 @@ Parameters with a leading `?` are optional. | Description | Client method | | ------------------------------------------------------------ | ------------- | -| Connect to a back-end, including authentication. Returns `Connection`. | `connect(url, ?authType, ?authOptions)` | +| Connect to a back-end, includes version discovery (`GET /well-known/openeo`), requesting capabilities and authentication where required. Returns `Connection`. | `connect(url, ?authType, ?authOptions)` | | Get client library version. | `clientVersion()` | #### Parameters @@ -106,6 +106,7 @@ Parameters with a leading `?` are optional. | Get the capabilities of the back-end. Returns `Capabilities`. | `GET /` | `capabilities()` | | List the supported output file formats. | `GET /output_formats` | `listFileTypes()` | | List the supported secondary service types. | `GET /service_types` | `listServiceTypes()` | +| List the supported UDF runtimes. | `GET /udf_runtimes` | `listUdfRuntimes()` | | List all collections available on the back-end. | `GET /collections` | `listCollections()` | | Get information about a single collection. | `GET /collections/{collection_id}` | `describeCollection(collection_id)` | | List all processes available on the back-end. | `GET /processes` | `listProcesses()` | @@ -114,13 +115,13 @@ Parameters with a leading `?` are optional. | Get information about the authenticated user. | `GET /me` | `describeAccount()` | | Lists all files from a user. Returns a list of `File`. | `GET /files/{user_id}` | `listFiles(?userId)` | | Opens a (existing or non-existing) file without reading any information. Returns a `File`. | *None* | `openFile(path, ?userId)` | -| Validates a process graph. | `POST /validate` | `validateProcessGraph(processGraph)` | +| Validates a process graph. | `POST /validation` | `validateProcessGraph(processGraph)` | | Lists all process graphs of the authenticated user. Returns a list of `ProcessGraph`. | `GET /process_graphs` | `listProcessGraphs()` | | Creates a new stored process graph. Returns a `ProcessGraph`. | `POST /process_graphs` | `createProcessGraph(processGraph, ?title, ?description)` | -| Get all information about a stored process graph. Returns a `ProcessGraph`. | `GET /process_graphs/{process_graph_id}` | `getJobById(id)` | -| Executes a process graph synchronously. | `POST /result` | `computeResult(processGraph, ?outputFormat, ?outputParameters, ?budget)` | +| Get all information about a stored process graph. Returns a `ProcessGraph`. | `GET /process_graphs/{process_graph_id}` | `getProcessGraphById(id)` | +| Executes a process graph synchronously. | `POST /result` | `computeResult(processGraph, ?plan, ?budget)` | | Lists all jobs of the authenticated user. Returns a list of `Job`. | `GET /jobs` | `listJobs()` | -| Creates a new job. Returns a `Job`. | `POST /jobs` | `createJob(processGraph, ?outputFormat, ?outputParameters, ?title, ?description, ?plan, ?budget, ?additional)` | +| Creates a new job. Returns a `Job`. | `POST /jobs` | `createJob(processGraph, ?title, ?description, ?plan, ?budget, ?additional)` | | Get all information about a job. Returns a `Job`. | `GET /jobs/{job_id}` | `getJobById(id)` | | Lists all secondary services of the authenticated user. Returns a list of `Service`. | `GET /services` | `listServices()` | | Creates a new secondary service. Returns a `Service`. | `POST /services` | `createService(processGraph, type, ?title, ?description, ?enabled, ?parameters, ?plan, ?budget)` | @@ -143,7 +144,7 @@ Should be prefixed with `Capabilities` if collisions of names between different | Get the description of the back-end. | `description` | `description()` | | List all supported features / endpoints. | `endpoints` | `listFeatures()` | | Check whether a feature / endpoint is supported. | `endpoints` > ... | `hasFeature(methodName)` | -| Get default billing currency. | `billing` > `currency` | `currency()` | +| Get the default billing currency. | `billing` > `currency` | `currency()` | | List all billing plans. | `billing` > `plans` | `listPlans()` | #### Parameters @@ -171,7 +172,7 @@ The `Job` scope internally knows the `job_id`. | Description | API Request | Client method | | ------------------------------------------ | ---------------------------------- | ------------- | | Get (and update on client-side) all job information. | `GET /jobs/{job_id}` | `describeJob()` | -| Modify a job at the back-end. | `PATCH /jobs/{job_id}` | `updateJob(?processGraph, ?outputFormat, ?outputParameters, ?title, ?description, ?plan, ?budget, ?additional)` | +| Modify a job at the back-end. | `PATCH /jobs/{job_id}` | `updateJob(?processGraph, ?title, ?description, ?plan, ?budget, ?additional)` | | Delete a job | `DELETE /jobs/{job_id}` | `deleteJob()` | | Calculate an time/cost estimate for a job. | `GET /jobs/{job_id}/estimate` | `estimateJob()` | | Start / queue a job for processing. | `POST /jobs/{job_id}/results` | `startJob()` | diff --git a/docs/processes.md b/docs/processes.md index d79c2cec..2daa5ee1 100644 --- a/docs/processes.md +++ b/docs/processes.md @@ -26,6 +26,7 @@ In addition to the native data formats specified by JSON schema, openEO defines | Format Name | Data type | Description | | ------------------------- | --------- | ----------- | +| `band-name` | string | A band name available in the data cube. | | `bounding-box` | object | A bounding box with the required fields `west`, `south`, `east`, `north` and optionally `base`, `height`, `crs`. The `crs` is a EPSG code or PROJ definition. | | `callback` | object | An openEO process graph that is passed as an argument and is expected to be executed by the process. Callback parameters are specified in a `parameters` property (see chapter "Callbacks" below). | | `collection-id` | string | A collection id from the list of supported collections. Pattern: `^[A-Za-z0-9_\-\.~/]+$` | diff --git a/docs/processgraphs.md b/docs/processgraphs.md index ebb415b3..21d38257 100644 --- a/docs/processgraphs.md +++ b/docs/processgraphs.md @@ -174,7 +174,7 @@ The process graph representing the algorithm: } }, "sub": { - "process_id": "substract", + "process_id": "subtract", "arguments": { "data": [{"from_node": "nir"}, {"from_node": "red"}] } diff --git a/errors.json b/errors.json index 63a3fcc6..4f0980ed 100644 --- a/errors.json +++ b/errors.json @@ -65,8 +65,8 @@ ] }, "BudgetInvalid": { - "description": "The specified budget is too low as it is either smaller than or equal to 0 or below the costs.", - "message": "The specified budget is too low.", + "description": "The budget is too low as it is either smaller than or equal to 0 or below the costs.", + "message": "The budget is too low.", "http": 400, "tags": [ "Job Management", @@ -85,7 +85,7 @@ }, "PropertyNotEditable": { "description": "For PATCH requests: The specified parameter can't be updated. It is read-only.", - "message": "Specified property '{property}' is read-only.", + "message": "Property '{property}' is read-only.", "http": 400, "tags": [ "Job Management", @@ -155,7 +155,7 @@ }, "ContentTypeInvalid": { "description": "The specified media (MIME) type used in the Content-Type header is not allowed.", - "message": "Media type specified in the request is not supported. Supported media types: {types}", + "message": "The media type is not supported. Allowed: {types}", "http": 400, "tags": [ "File Management", @@ -225,7 +225,7 @@ }, "VariableDefaultValueTypeInvalid": { "description": null, - "message": "The default value specified for the process graph variable '{variable_id}' is not of type '{type}'.", + "message": "The default value for the process graph variable '{variable_id}' is not of type '{type}'.", "http": 400, "tags": [ "Process Graph Management", @@ -243,7 +243,7 @@ }, "VariableTypeInvalid": { "description": null, - "message": "The data type specified for the process graph variable '{variable_id}' is invalid. Must be one of: string, boolean, number, array or object.", + "message": "The data type for the process graph variable '{variable_id}' is invalid. Must be one of: string, boolean, number, array or object.", "http": 400, "tags": [ "Process Graph Management", @@ -268,7 +268,7 @@ }, "ProcessArgumentInvalid": { "description": null, - "message": "The value specified for the process argument '{argument}' in process '{process}' is invalid: {reason}", + "message": "The argument '{argument}' in process '{process}' is invalid: {reason}", "http": 400, "tags": [ "Processes" @@ -284,7 +284,7 @@ }, "ProcessArgumentsMissing": { "description": null, - "message": "Process '{process}' requires at least '{min_parameters}' parameters.", + "message": "Process '{process}' requires at least {min_parameters} parameters.", "http": 400, "tags": [ "Processes" @@ -317,7 +317,7 @@ }, "FormatArgumentInvalid": { "description": null, - "message": "The value specified for the output format argument '{argument}' is invalid: {reason}", + "message": "The output format argument '{argument}' is invalid: {reason}", "http": 400, "tags": [ "Job Management" @@ -365,8 +365,8 @@ ] }, "BillingPlanInvalid": { - "description": "The specified billing plan is not on the list of available plans.", - "message": "The specified billing plan is not valid.", + "description": "The billing plan is not on the list of available plans.", + "message": "The billing plan is not valid.", "http": 400, "tags": [ "Job Management", @@ -431,7 +431,7 @@ }, "ServiceArgumentInvalid": { "description": null, - "message": "The value specified for the secondary service argument '{argument}' is invalid: {reason}", + "message": "The secondary service argument '{argument}' is invalid: {reason}", "http": 400, "tags": [ "Secondary Services Management" diff --git a/mkdocs.yml b/mkdocs.yml index 6e2a3871..d17df98e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: openEO API 0.4.0 +site_name: openEO API 0.4.1 nav: - Prologue: - Introduction: index.md diff --git a/openapi.json b/openapi.json index 1ede5ecf..ab68d947 100644 --- a/openapi.json +++ b/openapi.json @@ -14,8 +14,8 @@ ], "info": { "title": "openEO API", - "version": "0.4.0", - "description": "The openEO API specification for interoperable cloud-based processing of large Earth observation datasets.\n \n**Make sure to take account of several global API specifications**, which are not (fully) covered in this specification:\n * [Cross-Origin Resource Sharing (CORS) support](https://open-eo.github.io/openeo-api/v/0.4.0/cors/index.html) to allow browser-based access to the API.\n * [Error handling](https://open-eo.github.io/openeo-api/v/0.4.0/errors/index.html)\n * Unless otherwise stated the API works *case sensitive*.", + "version": "0.4.1", + "description": "The openEO API specification for interoperable cloud-based processing of large Earth observation datasets.\n \n**Make sure to take account of several global API specifications**, which are not (fully) covered in this specification:\n * [Cross-Origin Resource Sharing (CORS) support](https://open-eo.github.io/openeo-api/v/0.4.1/cors/index.html) to allow browser-based access to the API.\n * [Error handling](https://open-eo.github.io/openeo-api/v/0.4.1/errors/index.html)\n * Unless otherwise stated the API works *case sensitive*.", "contact": { "name": "openEO Consortium", "url": "http://www.openeo.org", @@ -28,7 +28,7 @@ }, "externalDocs": { "description": "openEO Documentation", - "url": "https://open-eo.github.io/openeo-api/v/0.4.0/" + "url": "https://open-eo.github.io/openeo-api/v/0.4.1/" }, "tags": [ { @@ -94,7 +94,7 @@ "api_version": { "type": "string", "description": "Version number of the openEO specification this back-end implements.", - "example": "0.4.0" + "example": "0.4.1" }, "backend_version": { "type": "string", @@ -340,7 +340,7 @@ "api_version": { "type": "string", "description": "Version number of the openEO specification this back-end implements.", - "example": "0.4.0" + "example": "0.4.1" } } } @@ -501,9 +501,9 @@ "description": "Set GeoPackage version. In AUTO mode, this will be equivalent to 1.2 starting with GDAL 2.3.", "enum": [ "auto", - 1, - 1.1, - 1.2 + "1", + "1.1", + "1.2" ], "default": "auto" }, @@ -547,7 +547,7 @@ "/collections": { "get": { "summary": "Basic metadata for all datasets.", - "description": "Lists available collections with basic information. To retrieve domain specific information (e.g. SAR) request all information for a specific collection using `GET /collections/{collection_id}`.\n\nThis endpoint is compatible with STAC 0.6.2 and all features and extensions of [STAC](https://github.com/radiantearth/stac-spec) can be used here.\n\n**Note:** openEO strives for compatibility with [STAC](https://github.com/radiantearth/stac-spec) and [OGC WFS 3](https://github.com/opengeospatial/WFS_FES) as far as possible. Both standards, as well as openEO, are still under development. Therefore, it is likely that further changes and adjustments will be made in the future.\n\nMore information on [data discovery](https://open-eo.github.io/openeo-api/v/0.4.0/collections/), including common relation types for links, are available in the documentation.", + "description": "Lists available collections with basic information. To retrieve domain specific information (e.g. SAR) request all information for a specific collection using `GET /collections/{collection_id}`.\n\nThis endpoint is compatible with STAC 0.6.2 and all features and extensions of [STAC](https://github.com/radiantearth/stac-spec) can be used here.\n\n**Note:** openEO strives for compatibility with [STAC](https://github.com/radiantearth/stac-spec) and [OGC WFS 3](https://github.com/opengeospatial/WFS_FES) as far as possible. Both standards, as well as openEO, are still under development. Therefore, it is likely that further changes and adjustments will be made in the future.\n\nMore information on [data discovery](https://open-eo.github.io/openeo-api/v/0.4.1/collections/), including common relation types for links, are available in the documentation.", "tags": [ "EO Data Discovery" ], @@ -748,7 +748,7 @@ ], "get": { "summary": "Full metadata for a specific dataset", - "description": "Lists all information about a specific collection specified by the identifier `collection_id`.\n\nThis endpoint is compatible with STAC 0.6.2 and all features and extensions of [STAC](https://github.com/radiantearth/stac-spec) can be used here.\n\n**Note:** openEO strives for compatibility with [STAC](https://github.com/radiantearth/stac-spec) and [OGC WFS 3](https://github.com/opengeospatial/WFS_FES) as far as possible. Both standards, as well as openEO, are still under development. Therefore, it is likely that further changes and adjustments will be made in the future.\n\nMore information on [data discovery](https://open-eo.github.io/openeo-api/v/0.4.0/collections/), including common relation types for links, are available in the documentation.", + "description": "Lists all information about a specific collection specified by the identifier `collection_id`.\n\nThis endpoint is compatible with STAC 0.6.2 and all features and extensions of [STAC](https://github.com/radiantearth/stac-spec) can be used here.\n\n**Note:** openEO strives for compatibility with [STAC](https://github.com/radiantearth/stac-spec) and [OGC WFS 3](https://github.com/opengeospatial/WFS_FES) as far as possible. Both standards, as well as openEO, are still under development. Therefore, it is likely that further changes and adjustments will be made in the future.\n\nMore information on [data discovery](https://open-eo.github.io/openeo-api/v/0.4.1/collections/), including common relation types for links, are available in the documentation.", "tags": [ "EO Data Discovery" ], @@ -882,11 +882,13 @@ ], "anyOf": [ { + "title": "Additional Dimension with Extent", "required": [ "extent" ] }, { + "title": "Additional Dimension with Values", "required": [ "values" ] @@ -988,11 +990,13 @@ ], "anyOf": [ { + "title": "Vertical Spatial Dimension with Extent", "required": [ "extent" ] }, { + "title": "Vertical Spatial Dimension with Values", "required": [ "values" ] @@ -1077,6 +1081,12 @@ } }, "anyOf": [ + { + "title": "STAC Other Extensions", + "description": "Any other extension from STAC or even custom extensions can be used to describe the collection better.", + "type": "object", + "additionalProperties": true + }, { "$ref": "#/components/schemas/collection_eo" }, @@ -1761,10 +1771,7 @@ "Account Management" ], "security": [ - {}, - { - "Bearer": [] - } + {} ], "responses": { "303": { @@ -1903,7 +1910,7 @@ "/result": { "post": { "summary": "Process and download data synchronously", - "description": "Process graphs will be executed directly and the result will be downloaded in the specified format. Requests might time-out after a certain amount of time by sending openEO error `RequestTimeout`. A header named `OpenEO-Costs` MAY be sent with all responses, which MUST include the costs for processing and downloading the data. This endpoint can be used to generate small previews or test process graphs before starting a batch job.", + "description": "Process graphs will be executed directly and the result will be downloaded in the format specified in the process graph. To specify the format use a process such as `save_result`. Requests might time-out after a certain amount of time by sending openEO error `RequestTimeout`. A header named `OpenEO-Costs` MAY be sent with all responses, which MUST include the costs for processing and downloading the data. This endpoint can be used to generate small previews or test process graphs before starting a batch job.", "tags": [ "Process Graph Management", "Batch Job Management" @@ -2946,7 +2953,17 @@ "example": 75.5 }, "error": { - "$ref": "#/components/schemas/job_error" + "oneOf": [ + { + "nullable": true, + "enum": [ + null + ] + }, + { + "$ref": "#/components/schemas/job_error" + } + ] }, "submitted": { "$ref": "#/components/schemas/submitted" @@ -3057,16 +3074,6 @@ } } }, - "424": { - "description": "The request can't be fulfilled as the batch job failed. This request will deliver the error message that was produced by the batch job.\n\nThis HTTP code MUST be sent only when the job `status` is `error`. The response to this error mirrors the `error` field in the `GET /jobs/{job_id}` repoonse.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/job_error" - } - } - } - }, "4XX": { "$ref": "#/components/responses/client_error_auth" }, @@ -3161,6 +3168,16 @@ } } }, + "424": { + "description": "The request can't be fulfilled as the batch job failed. This request will deliver the error message that was produced by the batch job.\n\nThis HTTP code MUST be sent only when the job `status` is `error`. The response to this error mirrors the `error` field in the `GET /jobs/{job_id}` repoonse.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/job_error" + } + } + } + }, "4XX": { "$ref": "#/components/responses/client_error_auth" }, @@ -3171,7 +3188,7 @@ }, "post": { "summary": "Start processing a batch job", - "description": "Adds a batch job to the processing queue to compute the results.\n\nThis endpoint has no effect if the job status is already `queued` or `running`. In particular, it doesn't restart a running job. Processing MUST be canceled before to restart it.\n\nThe job status is set to `queued`, if processing doesn't start instantly.\n* Once the processing starts the status is set to `running`.\n \n* Once the data is available to download the status is set to `finished`.\n \n* Whenever an error occurs during processing, the status must be set to `error`.", + "description": "Adds a batch job to the processing queue to compute the results.\n\nThe result will be stored in the format specified in the process graph. To specify the format use a process such as `save_result`.\n\nThis endpoint has no effect if the job status is already `queued` or `running`. In particular, it doesn't restart a running job. Processing MUST be canceled before to restart it.\n\nThe job status is set to `queued`, if processing doesn't start instantly.\n* Once the processing starts the status is set to `running`.\n \n* Once the data is available to download the status is set to `finished`.\n \n* Whenever an error occurs during processing, the status must be set to `error`.", "tags": [ "Batch Job Management" ], @@ -3508,7 +3525,7 @@ "/subscription": { "get": { "summary": "Subscribe to notifications", - "description": "Get notified when execution updates occure, e.g. status updates for a job, recently updated EO collections or added/deleted resources like files and process graphs.\n\n**Note:** There are two main differences for this request compared to regular API requests:\n\n1. WebSockets use the `wss://` protocol instead of `https://` - `ws://` is not allowed!\n2. The authorization token is sent in the web socket requests, not as HTTP header. See the `authorization` field in the openEO API for Subscriptions for more details.\n\nAfter upgrading from HTTP to the WebSockets protocol, the [openEO API for Subscriptions](https://open-eo.github.io/openeo-api/v/0.4.0/apireference-subscriptions/) applies for requests and responses.", + "description": "Get notified when execution updates occure, e.g. status updates for a job, recently updated EO collections or added/deleted resources like files and process graphs.\n\n**Note:** There are two main differences for this request compared to regular API requests:\n\n1. WebSockets use the `wss://` protocol instead of `https://` - `ws://` is not allowed!\n2. The authorization token is sent in the web socket requests, not as HTTP header. See the `authorization` field in the openEO API for Subscriptions for more details.\n\nAfter upgrading from HTTP to the WebSockets protocol, the [openEO API for Subscriptions](https://open-eo.github.io/openeo-api/v/0.4.1/apireference-subscriptions/) applies for requests and responses.", "tags": [ "Batch Job Management", "File Management", @@ -3611,7 +3628,7 @@ }, "link": { "title": "Link", - "description": "A link to another resource on the web. Bases on [RFC5899](https://tools.ietf.org/html/rfc5988) and SHOULD follow [registered link relation types](https://www.iana.org/assignments/link-relations/link-relations.xml) whenever feasible.", + "description": "A link to another resource on the web. Bases on [RFC 5899](https://tools.ietf.org/html/rfc5988).", "type": "object", "required": [ "href" @@ -3619,6 +3636,7 @@ "properties": { "rel": { "type": "string", + "description": "Relationship between the current document and the linked document. SHOULD be a [registered link relation type](https://www.iana.org/assignments/link-relations/link-relations.xml) whenever feasible.", "example": "related" }, "href": { @@ -3870,28 +3888,6 @@ "type": "number", "minimum": 0 } - }, - "sar:absolute_orbit": { - "description": "A list of absolute orbit numbers. Usually corresponds to the orbit count within the orbit cycle (e.g. ALOS, ERS-1/2, JERS-1, and RADARSAT-1, Sentinel-1). For UAVSAR it is the [Flight ID](http://uavsar.jpl.nasa.gov/cgi-bin/data.pl). A range can be specified as two element array in the array, e.g. `[25101, [25131, 25140]]` would be 25101 and 25131 to 25140.", - "type": "array", - "minItems": 1, - "items": { - "oneOf": [ - { - "type": "number", - "minimum": 0 - }, - { - "type": "array", - "minItems": 2, - "maxItems": 2, - "items": { - "type": "number", - "minimum": 0 - } - } - ] - } } } }, @@ -3909,18 +3905,21 @@ "description": "The recommended human-readable reference (citation) to be used by publications citing this collection. No specific citation style is suggested, but the citation should contain all information required to find the publication distinctively." }, "sci:publications": { - "type": "object", + "type": "array", "title": "STAC Scientific Publications", "description": "A list of publications which describe and reference the collection.", - "properties": { - "doi": { - "type": "string", - "description": "The DOI name of a publication which describes and references the collection. The publications should include more information about the collection and how it was processed. This MUST NOT be a DOIs link. For all DOI names respective DOI links SHOULD be added to the links section of the collection with relation type `cite-as`.", - "pattern": "^(10[.][0-9]{4,}(?:[.][0-9]+)*/(?:(?![%\"#? ])\\S)+)$" - }, - "citation": { - "type": "string", - "description": "Human-readable reference (citation) of a publication which describes and references the collection. The publications should include more information about the collection and how it was processed. No specific citation style is suggested, but a citation should contain all information required to find the publication distinctively." + "items": { + "type": "object", + "properties": { + "doi": { + "type": "string", + "description": "The DOI name of a publication which describes and references the collection. The publications should include more information about the collection and how it was processed. This MUST NOT be a DOIs link. For all DOI names respective DOI links SHOULD be added to the links section of the collection with relation type `cite-as`.", + "pattern": "^(10[.][0-9]{4,}(?:[.][0-9]+)*/(?:(?![%\"#? ])\\S)+)$" + }, + "citation": { + "type": "string", + "description": "Human-readable reference (citation) of a publication which describes and references the collection. The publications should include more information about the collection and how it was processed. No specific citation style is suggested, but a citation should contain all information required to find the publication distinctively." + } } } } @@ -4115,7 +4114,7 @@ "default": { "description": "Whenever no value for the variable is defined, the default value is used.", "nullable": true, - "oneOf": [ + "anyOf": [ { "type": "string" }, @@ -4174,7 +4173,7 @@ "title": "Process Argument Value", "description": "Arguments for a process. See the API documentation for more information.", "nullable": true, - "oneOf": [ + "anyOf": [ { "type": "string", "title": "String" @@ -4320,7 +4319,7 @@ } }, "sub": { - "process_id": "substract", + "process_id": "subtract", "arguments": { "data": [ { @@ -4493,14 +4492,10 @@ "default": false }, "deprecated": { - "type": "boolean", - "description": "Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.", - "default": false + "$ref": "#/components/schemas/process_deprecated" }, "experimental": { - "type": "boolean", - "description": "Specifies that a parameter is experimental and likely to change or produce unpredictable behaviour.", - "default": false + "$ref": "#/components/schemas/process_experimental" }, "media_type": { "$ref": "#/components/schemas/process_media_type" @@ -4532,14 +4527,11 @@ } }, "deprecated": { - "type": "boolean", - "description": "Declares this process to be deprecated. Consumers SHOULD refrain from usage of the declared process.", - "default": false + "$ref": "#/components/schemas/process_deprecated", + "type": "boolean" }, "experimental": { - "type": "boolean", - "description": "Declares this process to be still experimental, which means that it is likely to change or produce unpredictable behaviour.", - "default": false + "$ref": "#/components/schemas/process_experimental" }, "exceptions": { "type": "object", @@ -4563,7 +4555,7 @@ }, "http": { "type": "integer", - "description": "HTTP Status Code, following the [error handling conventions in openEO](https://open-eo.github.io/openeo-api/v/0.4.0/errors/). Defaults to `400`.", + "description": "HTTP Status Code, following the [error handling conventions in openEO](https://open-eo.github.io/openeo-api/v/0.4.1/errors/). Defaults to `400`.", "default": 400 } } @@ -4577,11 +4569,13 @@ "type": "object", "oneOf": [ { + "title": "Process Example with Process Graph", "required": [ "process_graph" ] }, { + "title": "Process Example with Arguments", "required": [ "arguments" ] @@ -4620,6 +4614,16 @@ "pattern": "^[A-Za-z0-9_]+$", "example": "ndvi" }, + "process_experimental": { + "type": "boolean", + "description": "Declares the process or parameter to be experimental, which means that it\n is likely to change or may produce unpredictable behaviour.\n Users should refrain from using it in production,\n but still feel encouraged to try it out and give feedback.", + "default": false + }, + "process_deprecated": { + "type": "boolean", + "description": "Specifies that the process or parameter is deprecated with the potential to\n be removed in any of the next versions. It should\n be transitioned out of usage as soon as possible and users\n should refrain from using it in new implementations.", + "default": false + }, "process_graph_id": { "type": "string", "description": "Unique identifier of a job that is generated by the back-end during job submission. MUST match the specified pattern.", @@ -4796,7 +4800,7 @@ }, "error": { "title": "General Error", - "description": "An error object declares addtional information about a client-side or server-side error. The [openEO documentation](https://open-eo.github.io/openeo-api/v/0.4.0/errors/index.html) provides additional information regarding error handling and a list of potential error codes.", + "description": "An error object declares addtional information about a client-side or server-side error. The [openEO documentation](https://open-eo.github.io/openeo-api/v/0.4.1/errors/index.html) provides additional information regarding error handling and a list of potential error codes.", "type": "object", "required": [ "code", @@ -4848,7 +4852,7 @@ "json_schema": { "type": "object", "title": "JSON Schema", - "description": "A schema object according to the specification of [JSON Schema draft-07](http://json-schema.org/). Additional values for `format` are defined [centrally in the API documentation](https://open-eo.github.io/openeo-api/v/0.4.0/processes/index.html), e.g. bbox or crs. Callback parameters are defined with the custom schema keyword `parameters`." + "description": "A schema object according to the specification of [JSON Schema draft-07](http://json-schema.org/). Additional values for `format` are defined [centrally in the API documentation](https://open-eo.github.io/openeo-api/v/0.4.1/processes/index.html), e.g. bbox or crs. Callback parameters are defined with the custom schema keyword `parameters`." }, "process_media_type": { "type": "string", @@ -4859,7 +4863,7 @@ "title": "Workspace File", "type": "object", "required": [ - "name" + "path" ], "properties": { "path": { diff --git a/processes b/processes index 69fc6aa3..cee65f77 160000 --- a/processes +++ b/processes @@ -1 +1 @@ -Subproject commit 69fc6aa3a0e32117ce781d01da65d14f0fc3c030 +Subproject commit cee65f77dece8568e350e65a67c9761a254e1aca diff --git a/subscriptions.json b/subscriptions.json index 7416295d..f3e715ba 100644 --- a/subscriptions.json +++ b/subscriptions.json @@ -2,7 +2,7 @@ "asyncapi": "1.2.0", "info": { "title": "openEO API for Subscriptions", - "version": "0.4.0", + "version": "0.4.1", "description": "The openEO API specification for interoperable cloud-based processing of large Earth observation datasets.\n\nThis is a subset of the openEO API that handles WebSocket-based protocols for subscriptions and notifications.\n\n`openeo.authorize`, `openeo.welcome`, `openeo.subscribe` and `openeo.unsubsribe` MUST be implemeneted by all back-ends.\n\n**Security considerations:** A handshake has to be performed directly after establishing the WebSocket connection. The client MUST send a `openeo.authorize` request and receives a `openeo.welcome` message after a successful authorization. The WebSocket connections MUST be closed by servers once a request with invalid authorization credentials is sent. Servers are allowed to close connections to clients that have not sent a `openeo.authorize` request 30 seconds after establishing a WebSocket connection.", "contact": { "name": "openEO Consortium", @@ -16,7 +16,7 @@ }, "externalDocs": { "description": "openEO Documentation", - "url": "https://open-eo.github.io/openeo-api/v/0.4.0/" + "url": "https://open-eo.github.io/openeo-api/v/0.4.1/" }, "baseTopic": "openeo", "topics": {