Skip to content

Commit 616cb18

Browse files
m-mohrm-mohr
authored
Merge pull request #136 from Open-EO/0.3.1
openEO API 0.3.1 - bugfix release
2 parents 58e0832 + 06274a2 commit 616cb18

19 files changed

+864
-270
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
__pycache__/
2+
.vscode
3+
site/

‎.travis.yml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,15 @@ sudo: required
1010
before_install:
1111
- pip install mkdocs
1212
- pip install mkdocs-material
13+
- pip install mkdocs-macros-plugin
1314
- pip install pymdown-extensions
1415
- pip install pygments
1516
- npm install -g asyncapi-docgen
1617

1718
install:
19+
- mv CHANGELOG.md docs/changelog.md
1820
- mkdocs build --clean
19-
- cp openapi.json site/
20-
- cp processes.json site/
21+
- cp *.json site/
2122
- rm -f site/apireference/index.html
2223
- rm -f site/processreference/index.html
2324
- rm -f site/apireference-subscriptions/index.html

‎CHANGELOG.md

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Changelog
2+
All notable changes to this project will be documented in this file.
3+
4+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
5+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6+
7+
## [0.3.1]
8+
9+
### Added
10+
- `createProcessGraph` method to client development guidelines.
11+
- JSON file with all specified errors.
12+
- Textual error codes for each specified error.
13+
- Allow setting a plan for `POST /preview`
14+
- Default billing plan in `GET /`.
15+
- Job ID in JSON response for `GET /jobs/{job_id}/results`.
16+
17+
### Changed
18+
- Several optional fields such as `output`, `title` and `description` are now nullable instead of requiring to omit them.
19+
- The output format is not required in `POST /preview` any more and thus allows falling back to the default.
20+
- The `output_format` parameter in `createJob` and `execute` in client development guidelines.
21+
- The `extent` parameters in `filter_bbox` and `filter_daterange` are formally required now.
22+
23+
### Deprecated
24+
- Numeric openEO error codes are soon to be replaced with textual error codes.
25+
- `eo:resolution` in collection bands is a duplicate of `eo:gsd`. Use `eo:gsd` instead.
26+
27+
### Fixed
28+
- Fixed a wrong definition of the header `OpenEO-Costs` in `POST /preview`.
29+
- Fixed typo in method `authenticateOIDC` in client development guidelines.
30+
- Fixed the definition of spatial extents by swapping north and south.
31+
- Replaced the outdated occurrences of `srs` with `crs` in spatial extents.
32+
- Added missing required descriptions to process definitions.
33+
- Added missing error messages.
34+
- Fixed unclear specification for arrays used as process graph arguments.
35+
36+
## [0.3.0] - 2018-09-21
37+
First version after proof of concept tackling many major issues. No changelog available.
38+
39+
## [0.0.2] - 2018-03-22
40+
Version for proof of concept. No changelog available.
41+
42+
## [0.0.1] - 2018-02-07
43+
Initial version.

‎README.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,29 @@
22

33
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.
44

5-
* **[Documentation / Specification](https://open-eo.github.io/openeo-api/v/0.3.0/index.html)**
5+
* **[Documentation / Specification](https://open-eo.github.io/openeo-api/v/0.3.1/index.html)**
66

77
## Versions
88

9-
The openEO (core) API is currently released in version **0.3**.
9+
The openEO (core) API is currently released in version **0.3.1**.
1010

1111
**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.
1212

1313
| Version / Branch | Status | Description |
1414
| ------------------------------------------------------------ | ------- | ------------------------------------------------------------ |
1515
| [0.0.1](https://github.com/Open-EO/openeo-api/tree/0.0.1) ([Spec](https://open-eo.github.io/openeo-api/v/0.0.1/index.html)) | legacy | First draft with basic ideas, loosely implemented. |
1616
| [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. |
17-
| [**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)) | current | Currently in implementation by clients and back-ends. Major rework. |
18-
| [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)) | planned | Fixing minor issues, see the changelog. |
19-
| [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)) | planned | Planned to add data set and process descriptions and an extension concept. |
17+
| [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. |
18+
| [**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)) | **current** | Fixing minor issues, see the changelog. |
19+
| [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)) | planned | Planned to improve data set descriptions, add process specifications and an extension concept. |
2020

21-
See also the [milestones](https://github.com/Open-EO/openeo-api/milestones) for a rough roadmap based on GitHub issues.
21+
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.
2222

2323
## Repository
2424

2525
This repository contains a set of files formally and technically describing the openEO API, each with a human-readable and easily browseable version:
2626

27-
* [openapi.json](openapi.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.3.0/apireference/)) provides the [openAPI](https://www.openapis.org/) 3.0 definition of the openEO API.
28-
* [processes.json](processes.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.3.0/processreference/)) defines pre-defined core processes back-ends may implement for best interoperability.
29-
* [subscriptions.json](subscriptions.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.3.0/apireference-subscriptions/)) provides the [AsyncAPI](https://www.asyncapi.com/) 1.2 definitions for the WebSocket-based subscriptions and notifications API for openEO.
30-
* [docs/](docs/) ([browseable version](https://open-eo.github.io/openeo-api/v/0.3.0/)) contains all additional written documentation, including 'getting started' guides, the architecture, feature descriptions, development guidelines and more.
27+
* [openapi.json](openapi.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.3.1/apireference/)) provides the [openAPI](https://www.openapis.org/) 3.0 definition of the openEO API.
28+
* [processes.json](processes.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.3.1/processreference/)) defines pre-defined core processes back-ends may implement for best interoperability.
29+
* [subscriptions.json](subscriptions.json) ([browseable version](https://open-eo.github.io/openeo-api/v/0.3.1/apireference-subscriptions/)) provides the [AsyncAPI](https://www.asyncapi.com/) 1.2 definitions for the WebSocket-based subscriptions and notifications API for openEO.
30+
* [docs/](docs/) ([browseable version](https://open-eo.github.io/openeo-api/v/0.3.1/)) contains all additional written documentation, including 'getting started' guides, the architecture, feature descriptions, development guidelines and more.

‎docs/.gitignore

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎docs/arch.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,9 @@ To simplify and structure the development, the API is divided into a few microse
2222
| Capabilities | This microservice reports on the capabilities of the back-end, i.e. which API endpoints are implemented, which authentication methods are supported, and whether and how UDFs can be executed at the back-end. |
2323
| EO Data Discovery | Describes which datasets and image collections are available at the back-end. |
2424
| Process Discovery | Provides services to find out which processes a back-end provides, i.e., what users can do with the available data. |
25-
| UDF Runtime Discovery | Allows discovering the programming languages and their runtime environments to execute user-defined functions. |
25+
| UDF | Discovery and execution of user-defined functions. |
2626
| Job Management | Organizes and manages jobs that run processes on back-ends. |
2727
| File Management | Organizes and manages user-uploaded files. |
2828
| Process Graph Management | Organizes and manages user-defined process graphs. |
2929
| Secondary Services Management | External web services to access data and job results such as a OGC WMTS service. |
30-
| User Content | User content and accounting. |
31-
| Authentication | Authentication of users. |
30+
| Account Management | User management, accounting and authentication. |

‎docs/errors.md

Lines changed: 6 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Sending `code` and `message` is REQUIRED.
2525

2626
* A back-end MAY add a free-form `id` (unique identifier) to the error response to be able to log and track errors with further non-disclosable details.
2727

28-
* The `code` is either one of the standardized openEO error codes below or a proprietary error code with a number greater than 10000.
28+
* The `code` is either one of the standardized openEO error codes below or a proprietary error code. Please note, that the numeric error code will be replaced by a descriptive textual code such as `SampleError` in API v0.4.0.
2929

3030
* 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.
3131

@@ -52,10 +52,10 @@ The openEO API often uses the following HTTP status codes for failed requests:
5252
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.
5353

5454
- **401 Unauthorized**:
55-
The client **did not** provide any authorization details (usually using the Authorization header), but authorization is required for this request to be processed.
55+
The client did not provide any authentication details for a resource requiring authentication or the provided authentication details are not correct.
5656

5757
- **403 Forbidden**:
58-
The client **did** provide authorization details (usually using the Authorization header), but the provided credentials or the authorization token is invalid or has expired.
58+
The client did provided correct authentication details, but the privileges/permissions of the provided credentials do not allow to request the resource.
5959

6060
- **404 Not Found**:
6161
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.
@@ -74,89 +74,8 @@ All HTTP status codes defined in RFC 7231 in the 400 and 500 ranges can be used
7474

7575
## openEO error codes
7676

77-
The following list of error codes is **incomplete**. These error codes will evolve over time. If you are missing any common error, please contribute it by adding an [issue](https://github.com/Open-EO/openeo-api/issues/new), creating a pull request or get in contact in our [chat room](https://openeo-chat.eodc.eu/channel/public).
77+
The following table of error codes is **incomplete**. These error codes will evolve over time. If you are missing any common error, please contribute it by adding an [issue](https://github.com/Open-EO/openeo-api/issues/new), creating a pull request or get in contact in our [chat room](https://openeo-chat.eodc.eu/channel/public).
7878

79-
### General error codes (xxx)
79+
The whole table of error codes is available as [JSON file](../errors.json), which can be used by implementors to automatically generate error responses.
8080

81-
82-
| openEO Error Code | Description | Message | HTTP Status Code |
83-
| ------- | ---------------------------- | ---------------- | ---------------- |
84-
| 404 | To be used if the value of a path parameter is invalid, i.e. the requested resource is not available. *Note:* Unsupported endpoints MUST use code 501. | Not Found. | 404 |
85-
| 501 | The back-end responds with this error code whenever an endpoint is specified in the openEO API, but is not supported. | Not implemented. | 501 |
86-
| 503 | | Service unavailable. | 503 |
87-
| 601 | | Parameter **X** is invalid. | 400 |
88-
| 611 | Invalid or unsupported CRS specified. | Invalid CRS specified. | 400 |
89-
| 612 | | Coordinate is out of bounds. | 400 |
90-
91-
### Capabilities (11xx)
92-
93-
None yet.
94-
95-
### Data and process discovery (12xx)
96-
97-
None yet.
98-
99-
### UDFs (13xx)
100-
101-
| openEO Error Code | Description | Message | HTTP Status Code |
102-
| ----------------- | ----------- | --------------------------------------- | ---------------- |
103-
| 1301 | | UDF programming language not supported. | 400 / 404 |
104-
| 1302 | | UDF type not supported. | 400 / 404 |
105-
106-
### File Handling (14xx)
107-
108-
| openEO Error Code | Description | Message | HTTP Status Code |
109-
| ----------------- | -------------------------------------------------------- | ------------------------ | ---------------- |
110-
| 1401 | Server couldn't store file due to server-side reasons. | Unable to store file. | 500 |
111-
| 1402 | The storage quota has been exceeded by the user. | Insufficient Storage. | 400 |
112-
| 1410 | File format, file extension or mime type is not allowed. | File type not allowed. | 400 |
113-
| 1411 | File exceeds allowed maximum file size. | File size it too large. | 400 |
114-
| 1412 | The content of the file is invalid. | File content is invalid. | 400 |
115-
| 1413 | The file is locked by a running job or another process. | File is locked. | 400 |
116-
117-
118-
### Process graphs (2xxx)
119-
120-
| openEO Error Code | Description | Message | HTTP Status Code |
121-
| ----------------- | ----------- | ------------------------------------------------------------ | ---------------- |
122-
| 2001 | | No process graph specified. | 400 |
123-
| 2002 | | Process graph structure is invalid. | 400 |
124-
| 2003 | | The array **X** contains values of multiple types. | 400 |
125-
| 2101 | | Process **X** is not supported. | 400 |
126-
| 2102 | | Process argument **X** is not supported. | 400 |
127-
| 2103 | | Invalid value **Y** for the process argument **X** specified. | 400 |
128-
| 2104 | | Required process argument **X** is missing. | 400 |
129-
130-
### Jobs (3xxx)
131-
132-
| openEO Error Code | Description | Message | HTTP Status Code |
133-
| ----------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ---------------- |
134-
| 408 | The (synchronous) request timed out. | Request timed out. | 408 |
135-
| 3001 | | Output format not supported. | 400 |
136-
| 3002 | | Output format argument **X** is not supported. | 400 |
137-
| 3003 | | Invalid value **Y** for the output format argument **X** specified. | 400 |
138-
| 3004 | | Data can't be transformed into the requested output format. | 400 |
139-
| 3005 | The job is currently locked due to an enabled service or a running batch computation and can't be modified meanwhile. | Job is locked. | 400 |
140-
| 3006 | The job has not finished computing the results yet. Try again later. | Results are not finished yet. | 400 |
141-
142-
### Authorization, user content and billing (401-403, 4xxx)
143-
144-
| openEO Error Code | Description | Message | HTTP Status Code |
145-
| ----------------- | ------------------------------------------------------------ | ---------------------------------------- | ---------------- |
146-
| 401 | The back-end responds with this error code whenever the HTTP status code 401 is appropriate (see above) and no other openEO error code in the 4000 range is suitable. | Unauthorized. | 401 |
147-
| 402 | The budget required to fulfil the request are insufficient. | Payment required. | 402 |
148-
| 403 | The back-end responds with this error code whenever the HTTP status code 403 is appropriate (see above) and no other openEO error code in the 4000 range is suitable. | Forbidden. | 403 |
149-
| 4001 | The specified password is not considered secure by the policy of the back-end provider or no password was given at all. The user needs to specify a different password to proceed. | Password does not meet the requirements. | 400 |
150-
| 4031 | Invalid authentication scheme (e.g. Bearer). | | 403 |
151-
| 4032 | Authorization token invalid or expired. | | 403 |
152-
| 4033 | | Credentials are not correct. | 403 |
153-
154-
### Seondary web services (5xxx)
155-
156-
| openEO Error Code | Description | Message | HTTP Status Code |
157-
| ----------------- | ------------------------- | ------------------------------------------------------------ | ---------------- |
158-
| 5001 | | Service type is not supported. | 400 |
159-
| 5101 | Invalid job id specified. | Job does not exist. | 400 |
160-
| 5102 | | Service argument **X** is not supported. | 400 |
161-
| 5103 | | Invalid value **Y** for the service argument **X** specified. | 400 |
162-
| 5104 | | Required service argument **X** is missing. | 400 |
81+
{{ error_codes() }}

0 commit comments

Comments
 (0)