Merge remote-tracking branch 'origin/0.4.1'

.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"

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.

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.

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()` |

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_\-\.~/]+$` |

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"}]
             }

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"

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