├── .github └── workflows │ ├── docs.yml │ └── tests.yml ├── .gitignore ├── .spectral.yml ├── CHANGELOG.md ├── CNAME ├── LICENSE ├── README.md ├── assets ├── pg-evi-example.json ├── pg-evi-example.png └── pg-schema.json ├── errors.json ├── extensions ├── commercial-data │ ├── README.md │ ├── openapi.yaml │ └── package.json └── federation │ └── README.md ├── openapi.yaml └── package.json /.github/workflows/docs.yml: -------------------------------------------------------------------------------- 1 | name: Deploy API Spec 2 | on: 3 | release: 4 | types: [published] 5 | push: 6 | branches: 7 | - draft 8 | - master 9 | jobs: 10 | deploy: 11 | runs-on: ubuntu-latest 12 | steps: 13 | - name: Inject env variables 14 | uses: rlespinasse/github-slug-action@v3.x 15 | - uses: actions/setup-node@v3 16 | with: 17 | node-version: 'lts/*' 18 | - uses: actions/checkout@v3 19 | - run: | 20 | npm install 21 | npm run build 22 | - name: clone gh-pages and clean-up 23 | if: ${{ env.GITHUB_REF_SLUG == 'master' }} 24 | run: | 25 | git clone --branch gh-pages https://github.com/Open-EO/openeo-api.git gh-pages 26 | find gh-pages -maxdepth 1 -type f -delete 27 | rm -rf gh-pages/assets/ 28 | - name: create empty gh-pages folder 29 | if: ${{ env.GITHUB_REF_SLUG != 'master' }} 30 | run: mkdir gh-pages 31 | - run: | 32 | cp redoc.html gh-pages/index.html 33 | cp errors.json gh-pages/errors.json 34 | cp -rv assets/. gh-pages/assets/ 35 | - name: deploy to root (master) 36 | uses: peaceiris/actions-gh-pages@v3 37 | if: ${{ env.GITHUB_REF_SLUG == 'master' }} 38 | with: 39 | github_token: ${{ secrets.GITHUB_TOKEN }} 40 | keep_files: true 41 | publish_dir: gh-pages 42 | user_name: 'openEO CI' 43 | user_email: openeo.ci@uni-muenster.de 44 | - name: deploy to ${{ env.GITHUB_REF_SLUG }} 45 | uses: peaceiris/actions-gh-pages@v3 46 | if: ${{ env.GITHUB_REF_SLUG != 'master' }} 47 | with: 48 | github_token: ${{ secrets.GITHUB_TOKEN }} 49 | publish_dir: gh-pages 50 | destination_dir: ${{ env.GITHUB_REF_SLUG }} 51 | user_name: 'openEO CI' 52 | user_email: openeo.ci@uni-muenster.de -------------------------------------------------------------------------------- /.github/workflows/tests.yml: -------------------------------------------------------------------------------- 1 | name: Test API Spec 2 | on: [push, pull_request] 3 | jobs: 4 | deploy: 5 | runs-on: ubuntu-latest 6 | steps: 7 | - uses: actions/setup-node@v3 8 | with: 9 | node-version: 'lts/*' 10 | - uses: actions/checkout@v3 11 | - name: Run tests 12 | run: | 13 | npm install 14 | npm test -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | __pycache__/ 2 | package-lock.json 3 | node_modules/ 4 | /redoc.html 5 | .vscode 6 | .idea 7 | -------------------------------------------------------------------------------- /.spectral.yml: -------------------------------------------------------------------------------- 1 | extends: "spectral:oas" 2 | # Work around broken rules: https://github.com/stoplightio/spectral/issues/1972 3 | except: 4 | "openapi.yaml#/paths/~1udf_runtimes/get/responses/200/content/application~1json/example": 5 | - oas3-valid-schema-example 6 | rules: 7 | contact-properties: true 8 | tag-description: true 9 | oas3-parameter-description: true 10 | oas3-unused-component: false # Broken: https://github.com/stoplightio/spectral/issues/1271 11 | operation-summary-formatted: 12 | description: Operation `summary` should start with upper case and not end with a dot. 13 | given: '$.paths.*[?( @property === ''get'' || @property === ''put'' || @property === ''post'' || @property === ''delete'' || @property === ''options'' || @property === ''head'' || @property === ''patch'' || @property === ''trace'' )]' 14 | then: 15 | field: summary 16 | function: pattern 17 | functionOptions: 18 | match: '^[A-Z].*[^\.]$' 19 | tags: 20 | - operation 21 | operation-id-kebab-case: 22 | given: "$..operationId" 23 | then: 24 | function: pattern 25 | functionOptions: 26 | match: ^[a-z][a-z0-9\-]*$ -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 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 | ## Unreleased / Draft 8 | 9 | ## [1.2.0] - 2021-05-31 10 | 11 | ### Added 12 | 13 | - **New extensions:** 14 | - [Commercial Data Extension](./extensions/commercial-data/README.md) 15 | - [Federation Extension](./extensions/federation/README.md) 16 | - `GET /`: New Relation types: [#404](https://github.com/Open-EO/openeo-api/issues/404) 17 | - `create-form` to link to the registration page 18 | - `recovery-form` to link to the credentials recovery page. 19 | - `GET /file_formats`: Add `pointcloud` to the `gis_data_types`. [#475](https://github.com/Open-EO/openeo-api/issues/475) 20 | - `GET /me`: New Relation types `alternate` and `related` for user-specific external pages. [#404](https://github.com/Open-EO/openeo-api/issues/404) 21 | - `GET /credentials/oidc`: Allow `authorization_code` and `urn:ietf:params:oauth:grant-type:device_code` (both without PKCE) as grants for `default_clients`. [#410](https://github.com/Open-EO/openeo-api/issues/410) 22 | - `GET /jobs` and `GET /jobs/{job_id}`: Added a links property that can for example link to results and logs. [#453](https://github.com/Open-EO/openeo-api/issues/453) 23 | - `GET /jobs/{job_id}/results`: 24 | - 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) 25 | - Added metadata field `openeo:status` to indicate the job status (and whether the result is complete or not). 26 | - 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) 27 | - `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) 28 | - 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) 29 | - `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) 30 | - Recommendation to add media types and titles to links for a better user experience. 31 | - 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) 32 | - Recommendation for UDF runtime names. [#409](https://github.com/Open-EO/openeo-api/issues/409) 33 | - Processes: Added `dimensions` schema for subtype `datacube` 34 | - Collections: Added `geometry` dimension type to `cube:dimensions` 35 | - New endpoint for metadata filters (queryables): `/collections/{collection_id}/queryables`. Also adds a new rel type to the collection links. [#396](https://github.com/Open-EO/openeo-api/issues/396) 36 | 37 | ### Changed 38 | 39 | - Updated STAC specification examples and references to v1.0.0, please see the [STAC changelog](https://github.com/radiantearth/stac-spec/blob/master/CHANGELOG.md) for all changes between 0.9 and 1.0. 40 | - `cube:dimensions`: `reference_system` is allowed to be PROJJSON, too. 41 | - Relaxed requirement that unsupported endpoints must return HTTP status code 501. Instead also HTTP status code 404 can be used (and is regularly used in practice). [#415](https://github.com/Open-EO/openeo-api/issues/415) 42 | - Minimum value for `costs` and `budget` is 0. 43 | - `GET /jobs/{job_id}/estimate`: If a batch job can't be estimated reliably, a `EstimateComplexity` error should be returned. [#443](https://github.com/Open-EO/openeo-api/issues/443) 44 | - The `/conformance` endpoint is now generally used for OGC APIs, STAC API and openEO. `conformsTo` is also exposed in `GET /` for STAC APIs. The openEO API and all extensions got individual conformance classes. [#186](https://github.com/Open-EO/openeo-api/issues/186) 45 | 46 | ### Fixed 47 | 48 | - Explicitly mention the use of HTTP content negotiation 49 | - Clarify that the default charset is UTF-8 [#462](https://github.com/Open-EO/openeo-api/issues/462) 50 | - Fixed inconsistencies in errors.json: removed `ProcessGraphIdDoesntMatch`, clarified `ProcessGraphMissing`, added `ProcessInvalid` and `ProcessGraphInvalid`. [#394](https://github.com/Open-EO/openeo-api/issues/394), [#395](https://github.com/Open-EO/openeo-api/issues/395), [#401](https://github.com/Open-EO/openeo-api/issues/401) 51 | - Fixed the default value for the version number in the API url (`v1.0` -> `v1`) and improved the description for API versioning. [#393](https://github.com/Open-EO/openeo-api/issues/393) 52 | - Fixed the Collection example to use `gsd` instead of `eo:gsd`. [#399](https://github.com/Open-EO/openeo-api/issues/399) 53 | - Clarify use of `user_id`. [#404](https://github.com/Open-EO/openeo-api/issues/404) 54 | - Clarify that the relation type `version-history` should include `/.well-known/openeo` in the URL. 55 | - Clarify that clients should (re-)request capabilities and discovery endpoints with token if available and supported. [#416](https://github.com/Open-EO/openeo-api/issues/416) 56 | - Clarify the fields `plan` (for processing requests) and `billing_plan` (in `GET /` and `GET /me`). [#425](https://github.com/Open-EO/openeo-api/issues/425) [#426](https://github.com/Open-EO/openeo-api/issues/426) 57 | - Clarified ambiguous batch job status changes. 58 | - Reflect that the `debug` process has been renamed to `inspect`. 59 | - Clarified uniqueness constraints for identifiers. [#449](https://github.com/Open-EO/openeo-api/issues/449) [#454](https://github.com/Open-EO/openeo-api/issues/454) 60 | - Clarified schematically the applicability of JSON Schema extensions (`parameters`, `returns`, `dimensions`) and their relation to the subtypes 61 | - `GET /`: Removed the superfluous default value for `currency`. [#423](https://github.com/Open-EO/openeo-api/issues/423) 62 | - `GET /credentials/oidc`: Clarify that clients may add additional scopes 63 | - `GET /me`: Clarify the behavior of the field `budget`. 64 | - `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs` and `POST /result`: Clarified the formatting of the `message` property. [#455](https://github.com/Open-EO/openeo-api/issues/455) 65 | - `GET /jobs/{job_id}/estimate`: Don't require that the costs are the upper limit. Services may specify the costs more freely depending on their terms of service. 66 | - `GET /services` and `GET /services/{service_id}`: Clarify that `enabled` is required by removing the default value. [#473](https://github.com/Open-EO/openeo-api/issues/473) 67 | - Several appearances of `nullable` were clarified according to the lint report by Spectral 68 | - Clarify how the well-known document works [#460](https://github.com/Open-EO/openeo-api/issues/460) 69 | - Clarify handling of JSON Schema versions 70 | 71 | ## [1.1.0] - 2021-05-17 72 | 73 | ### Added 74 | - `GET /processes` and `GET` / `PUT` for `/process_graphs/{process_graph_id}`: Allow specifying the return values processes receive from child processes. [#350](https://github.com/Open-EO/openeo-api/issues/350) 75 | - Recommendation that `POST /result` returns a `tar` file if the result consists of multiple files. [#349](https://github.com/Open-EO/openeo-api/issues/349) 76 | - `GET /credentials/oidc` can provide a set of default client ids for OpenID Connect. [#366](https://github.com/Open-EO/openeo-api/pull/366) 77 | - `experimental` and `deprecated` flags added for file formats, service types, udf runtimes, udf runtime versions, udf runtime libraries and all related parameters and schemas. [#354](https://github.com/Open-EO/openeo-api/issues/354) 78 | - `GET /jobs/{job_id}` and `GET /services/{service_id}`: `usage` property added for usage metrics. [#370](https://github.com/Open-EO/openeo-api/issues/370) 79 | - `GET /jobs/{job_id}/logs` and `GET /services/{service_id}/logs`: 80 | - `time` property added. [#330](https://github.com/Open-EO/openeo-api/issues/330) 81 | - `usage` property added to log entries. [#370](https://github.com/Open-EO/openeo-api/issues/370) 82 | - Added error `ResultLinkExpired`. [#379](https://github.com/Open-EO/openeo-api/issues/379) 83 | - `GET /me`: A default plan per user can be specified. [#375](https://github.com/Open-EO/openeo-api/issues/375) 84 | 85 | ### Changed 86 | 87 | - API doesn't discourage usage of `multipleOf` in JSON Schemas any longer. 88 | - `GET /jobs/{job_id}/results` supports to return a STAC Collection. [#343](https://github.com/Open-EO/openeo-api/issues/343) 89 | - Updated STAC schemas to better support versions 1.x.x. 90 | - The first extent in a Collection is always the overall extent, followed by more specific extents. [#369](https://github.com/Open-EO/openeo-api/issues/369) 91 | 92 | ### Fixed 93 | 94 | - Clarified how process exceptions should be used. [#352](https://github.com/Open-EO/openeo-api/issues/352) 95 | - Clarified that job results schould be stored as valid STAC catalogs. [#363](https://github.com/Open-EO/openeo-api/issues/363) 96 | - Clarified that job results require the property `datetime` and allow for additional properties. [#362](https://github.com/Open-EO/openeo-api/issues/362) 97 | - Clarified that billing plans, service names and file formats must be accepted case-insensitive. [#371](https://github.com/Open-EO/openeo-api/issues/371) 98 | - Clarified that the first provider listed at `GET /credentials/oidc` is the default provider for OpenID Connect. 99 | - Clarified that `GET /jobs/{job_id}/results` should always return valid signed URLs and the endpoint can be used to renew the signed URLs. [#379](https://github.com/Open-EO/openeo-api/issues/379) 100 | - Fixed casing of potential endpoints `GET /collections/{collection_id}/items` and `GET /collections/{collection_id}/items/{feature_id}`. 101 | - Clarified allowed characters in the `path` for uploaded user files. 102 | 103 | ## [1.0.1] - 2020-12-07 104 | 105 | ### Changed 106 | - `GET /collections` and `GET /collections/{collection_id}`: Units for STAC dimensions in `cube:dimensions` should be compliant to UDUNITS-2 units (singular) whenever available. 107 | - `GET /file_formats`: It is recommended to at least specify one of the data types in `gis_data_types`. [#325](https://github.com/Open-EO/openeo-api/issues/325) 108 | 109 | ### Fixed 110 | - Cross-Origin Resource Sharing (CORS): 111 | - **SECURITY**: It is recommended to set `Access-Control-Allow-Origin` to `*` instead of reflecting the origin. [#41](https://github.com/Open-EO/openeo-api/issues/41) 112 | - **SECURITY**: It is recommended to NOT send the `Access-Control-Allow-Credentials` header any more. [#41](https://github.com/Open-EO/openeo-api/issues/41) 113 | - Added missing `Link` header to `Access-Control-Expose-Headers`. [#331](https://github.com/Open-EO/openeo-api/issues/331) 114 | - `GET /`: Missing option `OPTIONS` added to allowed `methods` for the `endpoints`. [#324](https://github.com/Open-EO/openeo-api/issues/324) 115 | - For `PATCH` requests: Clarified that no default values apply (for `budget`, `enabled` and `plan`). Data is only changed on the back-end if new data is explicitly specified by the client. 116 | - For `POST` requests with a `plan` property: Clarify that the default value is `null`. 117 | - `GET /jobs/{job_id}/results`: Clarified the use of the `type` `Feature` in the GeoJSON result response. [#327](https://github.com/Open-EO/openeo-api/issues/327) 118 | - Add missing `{namespace}` placeholder to `ProcessUnsupported` error message. [#328](https://github.com/Open-EO/openeo-api/pull/328) 119 | - Fixed JSON Schema links to point to draft-07 instead of draft/2019-09. 120 | - `GET /jobs/{job_id}/estimate`: Enforce in the response schema that "at least one of `costs`, `duration` or `size` MUST be provided." 121 | 122 | ## [1.0.0] - 2020-07-17 123 | 124 | ### Added 125 | - `GET /me`: Added optional `name` property to better separate an internal user id from a displayable user name. Adopted description of `user_id` accordingly. 126 | - `GET /udf_runtimes`: 127 | - Added optional `title` property for UDF runtimes. [#266](https://github.com/Open-EO/openeo-api/issues/266) 128 | - Added required `type` property for UDF runtimes to support better code generation. 129 | - `GET /service_types`: Added optional `title` and `description` properties for service types. [#266](https://github.com/Open-EO/openeo-api/issues/266) 130 | - `GET /file_formats`: Added optional `description` property for file formats. [#266](https://github.com/Open-EO/openeo-api/issues/266) 131 | - `GET /collections/{collection_id}` and `GET /processes`: Mention of link `rel` type `example` to refer to examples. [#285](https://github.com/Open-EO/openeo-api/issues/285) 132 | - `GET /collections/{collection_id}`: Added optional `assets` property for collection-level assets. This may link to visualizations for example. [#211](https://github.com/Open-EO/openeo-api/issues/211) 133 | - `GET /collections`, `GET /jobs`, `GET /process_graphs`, `GET /services`: Allow all non-scalar properties to be part of the response although strongly discouraged. 134 | 135 | ### Changed 136 | - `GET /credentials/oidc`: field `scopes` is not required anymore, but when specified, it should contain the `openid` scope. [#288](https://github.com/Open-EO/openeo-api/pull/288) 137 | - `GET /.well-known/openeo` and `GET /`: `production` fields default to `false` instead of `true`. 138 | - `GET /jobs/{job_id}/logs` and `GET /services/{service_id}/logs`: `path` property is not required any longer. [#320](https://github.com/Open-EO/openeo-api/issues/320) 139 | - `GET /file_formats`: `parameters` is now required for each file format. [#318](https://github.com/Open-EO/openeo-api/issues/318) 140 | - `GET /service_types`: `configuration` and `process_parameters` are now required for each service. [#318](https://github.com/Open-EO/openeo-api/issues/318) 141 | - `GET /service_types` and `GET /file_formats`: 142 | - Allow full JSON Schema for parameters, instead of a very limited subset. 143 | - Instead of the proprietary property `example` use `examples` from JSON Schema instead. 144 | - `GET /collections` and `GET /collections/{collection_id}`: 145 | - Additional dimensions in `cube:dimensions` can only be of type `other`. 146 | - The extents `interval` and `bbox` can have multiple entries. 147 | - Allow all STAC versions that are compatible to STAC 0.9.0. 148 | - Process graph nodes have an additional field `namespace` to distinguish predefined and user-defined processes. The default behavior has not changed. [#305](https://github.com/Open-EO/openeo-api/issues/305) 149 | - Added `format: commonmark` to all properties supporting CommonMark formatting. 150 | - `errors.json`: The predefined error messages have been reworked. [#272](https://github.com/Open-EO/openeo-api/issues/272), [#273](https://github.com/Open-EO/openeo-api/issues/273) 151 | - Added `FolderOperationUnsupported`, `UnsupportedApiVersion`, `PermissionsInsufficient`, `ProcessGraphIdDoesntMatch` and `PredefinedProcessExists`. 152 | - Added variable `reason` to error `FilePathInvalid` and `type` to `FileTypeInvalid` and`ServiceUnsupported`. 153 | - Replaced the following error messages. The variables in the messages may have changed, too. 154 | - `ProcessArgumentUnsupported` -> `ProcessParameterUnsupported` 155 | - `ProcessArgumentInvalid` -> `ProcessParameterInvalid` 156 | - `ProcessParameterMissing` and `ProcessArgumentRequired` -> `ProcessParameterRequired` 157 | - `ServiceArgumentUnsupported` -> `ServiceConfigUnsupported` 158 | - `ServiceArgumentInvalid` -> `ServiceConfigInvalid` 159 | - `ServiceArgumentRequired` -> `ServiceConfigRequired` 160 | - Removed all error messages with tag `Processes` (`CRSInvalid`, `CoordinateOutOfBounds`) or related to storing file formats (`FormatUnsupported`, `FormatArgumentUnsupported`, `FormatArgumentInvalid`, `FormatUnsuitable`) as they are usually defined directly in the process specification as `exceptions`. 161 | 162 | ### Removed 163 | - `GET /processes`: Examples containing process graphs. Use links with `rel` type `example` and `type` set to `application/json` instead. [#285](https://github.com/Open-EO/openeo-api/issues/285) 164 | - `subtype-schemas.json`. It's now published as part of [openeo-processes](https://github.com/Open-EO/openeo-processes/blob/master/meta/subtype-schemas.json). 165 | 166 | ### Fixed 167 | - `/.well-known/openeo`: 168 | - Clarified that version numbers must be unique. [#287](https://github.com/Open-EO/openeo-api/issues/287) 169 | - Clarified that non-production ready versions should be connected to if no production-ready version is supported. [#289](https://github.com/Open-EO/openeo-api/issues/289) 170 | - `GET /jobs/{job_id}/results`: Clarified that unlocated results set `geometry` to `null` and omit the `bbox` property. 171 | - `GET /jobs/{job_id}/logs`: Clarified that back-ends can log at any stage of the job. [#315](https://github.com/Open-EO/openeo-api/issues/315) 172 | - `POST /jobs` and `POST /services`: Clarified definition of `Location` header in `HTTP 201` responses. [#269](https://github.com/Open-EO/openeo-api/issues/269) 173 | - `GET /service/{service_id}`: Property `configuration` is required instead of a non-existing property named `parameters`. 174 | - `POST /validation`: Clarify that unresolvable process parameters must not throw. [#314](https://github.com/Open-EO/openeo-api/issues/314) 175 | - Formally forbid 5 elements in bounding boxes. 176 | - Re-use corresponding schema for header `OpenEO-Identifier` (adds `pattern`). 177 | - Parameters passed to child process graphs are not defined recursively any longer. [#268](https://github.com/Open-EO/openeo-api/issues/268) 178 | - Parameters for child process graphs are not specified for return values and service type parameters any longer. [#268](https://github.com/Open-EO/openeo-api/issues/268) 179 | - Clarified the expected behavior for process parameters, if a default value is given and the parameter is implicitly set to be required. [#303](https://github.com/Open-EO/openeo-api/issues/303) 180 | - Several clarifications and improvements for the documentation. 181 | 182 | ## [1.0.0-rc.2] - 2020-02-20 183 | 184 | ### Added 185 | - `PUT /process_graphs/{process_graph_id}` to store and replace custom process-graphs. [#260](https://github.com/Open-EO/openeo-api/issues/260) 186 | - `GET .../logs`: Reintroduced the missing `offset` parameter. 187 | 188 | ### Changed 189 | - For batch jobs (`/jobs`), services (`/services`) and sync. processing (`/result`) the property `process_graph` got replaced by `process`. It contains a process graph and optionally all process metadata. [#260](https://github.com/Open-EO/openeo-api/issues/260) 190 | - `GET /process_graphs`: Field `id` is required for each process. 191 | - Several properties in user-defined processes can now be `null` (see also [#264](https://github.com/Open-EO/openeo-api/issues/264)): 192 | - `GET /process_graphs` and `GET /process_graphs/{process_graph_id}`: Process properties `summary`, `description`, `parameters` and `returns`. 193 | - `POST /validation`: Process property `id`. 194 | - Child processes in process graphs (fka callbacks): `id`, `summary`, `description`, `parameters` and `returns`. 195 | 196 | ### Removed 197 | - `POST /process_graphs` and `PATCH /process_graphs/{process_graph_id}`. Use `PUT /process_graphs/{process_graph_id}` instead. [#260](https://github.com/Open-EO/openeo-api/issues/260) 198 | 199 | ### Fixed 200 | - Added `$id` to JSON Schema file for subtypes. 201 | - Fixed invalid EPSG code example. 202 | - Fixed collection example (`sat:cloud_cover` changed to `eo:cloud_cover`). 203 | - Fixed invalid JSON Schema for process graph validation (used `from_argument` instead of `from_parameter`). 204 | - Clarified how version numbers in well-known discovery are compared. [#259](https://github.com/Open-EO/openeo-api/issues/259) 205 | - Clarified that back-ends not supporting pagination will return all resources. 206 | - Clarified how `from_parameter` is resolved in case no value is given. 207 | - Clarified `GET .../logs` endpoint behaviour. 208 | - Clarify difference between STAC specification and STAC API. 209 | - Clarify that a copy of the STAC Item is recommended to be part of the assets in a batch job download. 210 | - Removed outdated error codes from `errors.json`. 211 | 212 | ## [1.0.0-rc.1] - 2020-01-31 213 | 214 | **Note:** The user and developer documentation has been moved to [openeo.org](https://openeo.org/documentation). 215 | 216 | ### Added 217 | 218 | - `GET /`: 219 | - Field `production` added to response. [#184](https://github.com/Open-EO/openeo-api/issues/184) 220 | - Required fields `stac_version` and `id` added to response for STAC compatibility. [#247](https://github.com/Open-EO/openeo-api/issues/247) 221 | - Links with relation types `terms-of-service` and `privacy-policy` explicitly documented. Clients must handle them properly if present. [#212](https://github.com/Open-EO/openeo-api/issues/212) 222 | - `GET /collections` and `GET /collections/{collectionId}`: 223 | - New field `deprecated` can be used to indicate outdated collections. Links with relation type `latest-version` can point to the latest version. [#226]( https://github.com/Open-EO/openeo-api/issues/226) 224 | - Added a Data Cube Dimension of type `bands` to the `cube:dimensions` property. [#208](https://github.com/Open-EO/openeo-api/issues/208) 225 | - `GET /conformance` has been added for OCG API compliance. Back-ends may implement it for compatibility with OGC API clients. 226 | - `POST /result`: May add a link to a log file in the header. [#214](https://github.com/Open-EO/openeo-api/issues/214) 227 | - `GET /jobs/{job_id}/logs` and `GET /services/{service_id}/logs`: Endpoints that publish logging information. [#214](https://github.com/Open-EO/openeo-api/issues/214) 228 | - `GET /files`, `GET /jobs`, `GET /process_graphs`, `GET /services`, `GET /collections`, `GET /processes`: Added `limit` parameter for pagination and clarified how to use links for pagination. [#103](https://github.com/Open-EO/openeo-api/issues/103) 229 | - JSON Schema for the defined schema `subtypes`. 230 | 231 | ### Changed 232 | 233 | - The concept of callbacks has simply been renamed to process graph. Schema format/subtype `callback` has been renamed to `process-graph`. [#216](https://github.com/Open-EO/openeo-api/issues/216) 234 | - Unsupported endpoints are not forced to return a `FeatureUnsupported` (501) error and can return a simple `NotFound` (404) instead. 235 | - If `currency` returned by `GET /` is `null`, `costs` and `budget` are unsupported. `costs` and `budget` fields in various endpoints can be set to `null` (default). 236 | - Official support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html). [#203](https://github.com/Open-EO/openeo-api/issues/203) 237 | - The parameter `user_id ` has been removed from the endpoints to manage user files (`/files/{user_id}`). [#218](https://github.com/Open-EO/openeo-api/issues/218) 238 | - Schema subtype `band-name` allows common band names, too. [Processes#77](https://github.com/Open-EO/openeo-processes/issues/77) 239 | - Link property `rel` is required. 240 | - OpenAPI string format `url` has been replaced with `uri`. 241 | - Process graphs: 242 | - `from_argument` has been renamed to `from_parameter`. 243 | - `callback` has been renamed to `process_graph`. 244 | - `from_parameter` can access parameters defined in parent scopes. 245 | - `from_parameter` can be used in the top-level process graph. 246 | - Process graph variables (objects with `variable_id` etc.) have been removed. 247 | - `GET /jobs`, `GET /jobs/{job_id}`, `GET /services` and `GET /services/{service_id}`: Renamed field `submitted` to `created` for consistency with STAC job results. Also renamed the corresponding value in the field `status` for batch jobs. 248 | - `GET /`: Property `links` is required. 249 | - `GET /service_types`: `variables` has been renamed to `process_parameters` and has a different schema now. [#161](https://github.com/Open-EO/openeo-api/issues/161) 250 | - `GET /service_types`, `POST /services`, `GET /services/{service_id}`, `PATCH /services/{service_id}`: `parameter` has been renamed to `configuration` to not overlap with `process_parameters`. 251 | - `GET /processes`: 252 | - Default values are now specified on the parameter-level, not in the JSON schemas. 253 | - Multiple data types in parameters or return values are supported as arrays. Using `anyOf` is discouraged. 254 | - Parameters are defined as array. `parameter_order` is therefore removed and the name is part of the parameter object. [#239](https://github.com/Open-EO/openeo-api/issues/239) 255 | - Process graph (callback) parameters have a new, more advanced schema, allowing to define more aspects of the process graph parameters. [#239](https://github.com/Open-EO/openeo-api/issues/239) 256 | - Return values don't require a description any longer. 257 | - `required` was replaced with `optional` with inverted behavior. 258 | - `POST /process_graphs`,`GET /process_graphs/{process_graph_id}`, `PATCH /process_graphs/{process_graph_id}`, `POST /validation`: Request and response bodies have been completely reworked to follow the same schema as `GET /processes`. Each process graph is now basically a process a user can use in other process graphs. 259 | - `GET /collections` and `GET /collections/{collectionId}`: Updated STAC to version 0.9.0. See the [STAC Changelog](https://github.com/radiantearth/stac-spec/blob/master/CHANGELOG.md) for more details. [#247](https://github.com/Open-EO/openeo-api/issues/247), [#204](https://github.com/Open-EO/openeo-api/issues/204). 260 | - `GET /credentials/oidc`: Changed response to support multiple OpenID Connect identity providers ([#201](https://github.com/Open-EO/openeo-api/issues/201)) and clarified workflow overall. 261 | - Bearer token are built from the authentication method, an optional provider id and the token itself. [#219](https://github.com/Open-EO/openeo-api/issues/219) 262 | - `GET /udf_runtimes`: `description` fields don't allow `null` values any longer. 263 | - `GET /output_formats` renamed to `GET /file_formats` to allow listing input file formats. [#215](https://github.com/Open-EO/openeo-api/issues/215) 264 | - The structure of the response has changed. The former response body for the output formats is now available in the property `output`. 265 | - The input file formats are now available in the property `input` with the same schema as for output formats. 266 | - Additionally, each format can have a `title`. 267 | - `GET /jobs/{job_id}/results`: 268 | - Response body for status code 200 has changed to be a valid STAC Item, allows content type `application/geo+json`. 269 | - Response body for status code 424 has been extended. 270 | 271 | ### Deprecated 272 | 273 | - The processes should not use the JSON Schema keyword `format` any longer. Instead use the custom keyword `subtype`. [#233](https://github.com/Open-EO/openeo-processes/issues/233) 274 | - PROJ definitions are deprecated in favor of EPSG codes and WKT2. [#58](https://github.com/Open-EO/openeo-processes/issues/58) 275 | 276 | ### Removed 277 | 278 | - Process graph variables. Use Parameter References instead. 279 | - `GET /processes`: `media_type` removed from parameters and return values. Use `contentMediaType` in the JSON Schema instead. 280 | - `GET /job/{job_id}`: Removed property `error`. Request information from `GET /job/{job_id}/logs` instead. 281 | - `GET /job/{job_id}/results`: 282 | - Metalink XML encoding has been removed. [#205](https://github.com/Open-EO/openeo-api/issues/205) 283 | - `Expires` header has been removed, use `expires` property in the response body instead. 284 | - `GET /credentials/basic` doesn't return a `user_id`. Instead request it from `GET /me`. 285 | - `GET /collections/{collectionId}`: Removed optional STAC extensions from the API specification. Inform yourself about useful [STAC extensions](https://github.com/radiantearth/stac-spec/tree/master/extensions#list-of-content-extensions) instead. [#176](https://github.com/Open-EO/openeo-api/issues/176) 286 | - `GET /service_types` doesn't support `attributes` any longer. 287 | 288 | ### Fixed 289 | 290 | - Service parameters and attributes in `GET /service_types` and output format parameters in `GET /file_formats` (previously `GET /output_formats`) now have a `type`, which was previously only mentioned in examples. 291 | - `GET /processes`: Parameters `arguments` and `process_graph` can't be used together in process examples. 292 | - `GET ./well-known/openeo`: Clarified how clients and back-ends should implement well-known discovery. [#202](https://github.com/Open-EO/openeo-api/issues/202) 293 | 294 | ## [0.4.2] - 2019-06-11 295 | 296 | ### Added 297 | - Basic JSON Schema for process graph validation. 298 | 299 | ### Changed 300 | - Updated the process catalog, see the separate changelog. 301 | 302 | ### Removed 303 | - Disallowed CommonMark in descriptions of process graph variables and process graph nodes. 304 | 305 | ### Fixed 306 | - Improved documentation with several clarifications, better examples and more. 307 | - SAR Bands had a required but undefined property. [#187](https://github.com/Open-EO/openeo-api/issues/187) 308 | - Clarified how file paths in the URL must be encoded for file handling. 309 | - OpenAPI `nullable` issues: 310 | - Removed `null` from SAR Bands `enum` for OpenAPI code generator, is handled by `nullable`. [OpenAPI-Specification#1900](https://github.com/OAI/OpenAPI-Specification/issues/1900) 311 | - `nullable` doesn't combine well with `anyOf`, `allOf` and `oneOf`, therefore placed `nullable` also in one of the sub-schemas. [OpenAPI-Specification#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368) 312 | 313 | ## [0.4.1] - 2019-05-29 314 | 315 | ### Changed 316 | - Updated the process catalog, see the separate changelog. 317 | 318 | ### Removed 319 | - The property `sar:absolute_orbit` in `GET /collections/{collection_id}` has been removed. 320 | - Sending a Bearer token to `GET /credentials/oidc` is not allowed any longer. 321 | 322 | ### Fixed 323 | - Improved and clarified the documentation and descriptions. 324 | - `GET /collections/{collection_id}`: 325 | - `properties` in `GET /collections/{collection_id}` doesn't require any of the integrated STAC extensions any longer. 326 | - 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. 327 | - `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) 328 | - `path` in `GET` and `PUT` `/files/{user_id}` is required again. 329 | - Fixed several issues in the client development guidelines. 330 | 331 | ## [0.4.0] - 2019-03-07 332 | 333 | ### Added 334 | - `GET /jobs/{job_id}/estimate` can return the estimated required storage capacity. [#122](https://github.com/Open-EO/openeo-api/issues/122) 335 | - `GET /jobs/{job_id}` has two new properties: 336 | - `progress` indicates the batch job progress when running. [#82](https://github.com/Open-EO/openeo-api/issues/82) 337 | - `error` states the error message when a job stopped due to an error. 338 | `GET /jobs/{job_id}/result` mirrors this error message in a response with HTTP status code 424. [#165](https://github.com/Open-EO/openeo-api/issues/165) 339 | - `GET /.well-known/openeo` allows clients to choose between versions. [#148](https://github.com/Open-EO/openeo-api/issues/148) 340 | - `GET /` (Capabilities): 341 | - Requires to return a title (`title`), a description (`description`) and the back-end version (`backend_version`). [#154](https://github.com/Open-EO/openeo-api/issues/154) 342 | - Billing plans have an additional required property `paid`. [#157](https://github.com/Open-EO/openeo-api/issues/157) 343 | - Should provide a link to the Well-Known URI (`/.well-known/openeo`) in the new `links` property. 344 | - `GET /processes` (Process discovery): 345 | - Processes can be categorizes with the `category` property. 346 | - Parameters can be ordered with the `parameter_order` property instead of having a random order. 347 | - Support for references to other processes in descriptions. 348 | - Processes and parameters can be declared to be `experimental`. 349 | - `GET /output_formats` and `GET /service_types` can now provide links per entry. 350 | - `GET /udf_runtimes` provide a list of UDF runtime environments. [#87](https://github.com/Open-EO/openeo-api/issues/87) 351 | - `GET /service_types` allows to specify `variables` that can be used in process graphs. [#172](https://github.com/Open-EO/openeo-api/issues/172) 352 | 353 | ### Changed 354 | - Completely new version of the processes. 355 | - Changed process graph to a flexible graph-like structure, which also allows callbacks. [#160](https://github.com/Open-EO/openeo-api/issues/160) 356 | - Updated `GET /collections` and `GET /collections/{collection_id}` to follow STAC v0.6.2. [#158](https://github.com/Open-EO/openeo-api/issues/158), [#173](https://github.com/Open-EO/openeo-api/issues/173) 357 | - The `process_graph_id` of stored process graphs, the `service_id` of services and the `job_id` of jobs has changed to `id` in responses. [#130](https://github.com/Open-EO/openeo-api/issues/130) 358 | - The `status` property for jobs is now required. 359 | - `POST /preview` renamed to `POST /result`. [#162](https://github.com/Open-EO/openeo-api/issues/162) 360 | - `GET /` (Capabilities): 361 | - `version` in the response was renamed to `api_version`. 362 | - Endpoint paths must follow the openAPI specification. [#128](https://github.com/Open-EO/openeo-api/issues/128) 363 | - Billing plan descriptions allow CommonMark. [#164](https://github.com/Open-EO/openeo-api/issues/164) 364 | - `/files/{user_id}/{path}` File management: 365 | - Clarified handling of folders. [#146](https://github.com/Open-EO/openeo-api/issues/146) 366 | - `GET` method: The `name` property was renamed to `path`. [#133](https://github.com/Open-EO/openeo-api/issues/133) 367 | - `PUT` method: Returns file meta data with a different response code. [#163](https://github.com/Open-EO/openeo-api/issues/163) 368 | - `GET /processes` (Process discovery): 369 | - The `name` property of processes has changed to `id`. [#130](https://github.com/Open-EO/openeo-api/issues/130) 370 | - `mime_type` replaced with `media_type` in the input parameters and return values. 371 | - The schema for `exceptions` follows the general schema for openEO errors. [#139](https://github.com/Open-EO/openeo-api/issues/139) 372 | - Changed the structure of `examples`. 373 | - `POST /validation` (Process graph validation): 374 | - Returns HTTP status code 200 for valid and invalid process graphs and responds with a list of errors. [#144](https://github.com/Open-EO/openeo-api/issues/144) 375 | - Allowed to call the endpoint without authentication. [#151](https://github.com/Open-EO/openeo-api/issues/151) 376 | - Behavior for `DELETE /jobs/{job_id}/results` and `POST /jobs/{job_id}/results` specified depending on the job status. Clarified status changes in general. [#142](https://github.com/Open-EO/openeo-api/issues/142) 377 | - Improved client development guidelines. [#124](https://github.com/Open-EO/openeo-api/issues/124), [#138](https://github.com/Open-EO/openeo-api/issues/138) 378 | 379 | ### Removed 380 | - Numeric openEO error codes. Replaced in responses with textual error codes. [#139](https://github.com/Open-EO/openeo-api/issues/139) 381 | - Query parameters to replace process graph variables in `GET /process_graphs/{process_graph_id}`. [#147](https://github.com/Open-EO/openeo-api/issues/147) 382 | - `min_parameters` and `dependencies` for parameters in process descriptions returned by `GET /processes`. 383 | - Replaced output format properties in favor of a `save_result` process, which has resulted in in the removal of: 384 | - The default output format in `GET /output_formats`. [#153](https://github.com/Open-EO/openeo-api/issues/153) 385 | - The output format properties in `POST /result` (fka `POST /preview`), `POST /jobs`, `PATCH /jobs` and `GET /jobs/{job_id}` requests. [#153](https://github.com/Open-EO/openeo-api/issues/153) 386 | - `gis_data_type` (not to be confused with `gis_data_types`) in the parameters of output formats in `GET /output_formats` 387 | 388 | ### Fixed 389 | - Added missing `Access-Control-Expose-Headers` header to required CORS headers. 390 | - Some endpoints didn't include authentication information. 391 | - `GET /jobs/{job_id}/estimate`: Property `downloads_included` had a wrong default value. 392 | 393 | ## [0.3.1] - 2018-11-06 394 | 395 | ### Added 396 | - `createProcessGraph` method to client development guidelines. 397 | - JSON file with all specified errors. 398 | - Textual error codes for each specified error. 399 | - Allow setting a plan for `POST /preview` 400 | - Default billing plan in `GET /`. [#141](https://github.com/Open-EO/openeo-api/issues/141) 401 | - Job ID in JSON response for `GET /jobs/{job_id}/results`. 402 | 403 | ### Changed 404 | - Several optional fields such as `output`, `title` and `description` are now nullable instead of requiring to omit them. 405 | - The output format is not required in `POST /preview` any more and thus allows falling back to the default. 406 | - The `output_format` parameter in `createJob` and `execute` in client development guidelines. 407 | - The `extent` parameters in `filter_bbox` and `filter_daterange` are formally required now. 408 | 409 | ### Deprecated 410 | - Numeric openEO error codes are soon to be replaced with textual error codes. 411 | - `eo:resolution` in collection bands is a duplicate of `eo:gsd`. Use `eo:gsd` instead. 412 | 413 | ### Fixed 414 | - Fixed a wrong definition of the header `OpenEO-Costs` in `POST /preview`. 415 | - Fixed typo in method `authenticateOIDC` in client development guidelines. 416 | - Fixed the definition of spatial extents by swapping north and south. 417 | - Replaced the outdated occurrences of `srs` with `crs` in spatial extents. 418 | - Added missing required descriptions to process definitions. 419 | - Added missing error messages. 420 | - Fixed unclear specification for arrays used as process graph arguments. 421 | - Fixed inconsist schema of openEO error responses: Field is now consistently named `message` instead of `description`. 422 | 423 | ## [0.3.0] - 2018-09-21 424 | First version after proof of concept tackling many major issues. No changelog available. 425 | 426 | ## [0.0.2] - 2018-03-22 427 | Version for proof of concept. No changelog available. 428 | 429 | ## [0.0.1] - 2018-02-07 430 | Initial version. 431 | 432 | 433 | [Unreleased]: 434 | [1.2.0]: 435 | [1.1.0]: 436 | [1.0.1]: 437 | [1.0.0]: 438 | [0.4.2]: 439 | [0.4.1]: 440 | [0.4.0]: 441 | [0.3.0]: 442 | [0.0.2]: 443 | [0.0.1]: -------------------------------------------------------------------------------- /CNAME: -------------------------------------------------------------------------------- 1 | api.openeo.org -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "{}" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright {yyyy} {name of copyright owner} 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # openEO API 2 | 3 | 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. 4 | 5 | * **[Latest Version of the Specification](https://api.openeo.org)** 6 | 7 | ## Versions / Branches 8 | 9 | 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. 10 | 11 | | Version / Branch | Status | Description | 12 | | --------------------------------------------------------- | ----------- | ----------- | 13 | | [draft](https://api.openeo.org/draft) | planned | *Unstable* - Next version. | 14 | | [**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). | 15 | | [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). | 16 | | [1.0.1](https://api.openeo.org/1.0.1) | legacy | Clarifications, bugfixes and CORS improvements. [Changelog](CHANGELOG.md#101---2020-12-07). | 17 | | [1.0.0](https://api.openeo.org/1.0.0) | legacy | First stable version of openEO. [Changelog](CHANGELOG.md#100---2020-07-17). | 18 | | [1.0.0-rc.2](https://api.openeo.org/1.0.0-rc.2) | legacy | Introduced user-defined processes. [Changelog](CHANGELOG.md#100-rc2---2020-02-20). | 19 | | [1.0.0-rc.1](https://api.openeo.org/1.0.0-rc.1) | legacy | Better UDF support, support for file import, support for processing logs, better alignment with STAC and upcoming OGC APIs. Removes WebSocket-based Subscription API. [Changelog](CHANGELOG.md#100-rc1---2020-01-31) | 20 | | [0.4.2](https://api.openeo.org/v/0.4.2) | legacy | Bugfix release. [Changelog](CHANGELOG.md#042---2019-06-11). | 21 | | [0.4.1](https://api.openeo.org/v/0.4.1) | legacy | Bugfix release. [Changelog](CHANGELOG.md#041---2019-05-29). | 22 | | [0.4.0](https://api.openeo.org/v/0.4.0) | legacy | Improved discovery, added processes catalogue, new process graph structure. [Changelog](CHANGELOG.md#040---2019-03-07). | 23 | | [0.3.1](https://api.openeo.org/v/0.3.1) | legacy | Bugfix release. [Changelog](CHANGELOG.md#031---2018-11-06). | 24 | | [0.3.0](https://api.openeo.org/v/0.3.0) | legacy | Major rework. | 25 | | [0.0.2](https://github.com/Open-EO/openeo-api/tree/0.0.2) | legacy | Proof of concept, implemented. | 26 | | [0.0.1](https://github.com/Open-EO/openeo-api/tree/0.0.1) | legacy | First draft with basic ideas, loosely implemented. | 27 | 28 | 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. 29 | 30 | ## Extensions 31 | 32 | | Name | Version | Stability | Description | 33 | | ---------------------------------------------- | ------- | ------------ | ----------- | 34 | | [Commercial Data](extensions/commercial-data/) | 0.1.0 | experimental | Provides an interface for discovering, ordering and using commercial data. | 35 | | [Federation](extensions/federation/) | 0.1.0 | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. | 36 | 37 | ## Repository 38 | 39 | This repository contains a set of files formally describing the openEO API, each with a human-readable and easily browseable version: 40 | 41 | * [openapi.yaml](openapi.yaml) provides the [OpenAPI](https://www.openapis.org/) 3.0 definition of the openEO API. See the table above for human-readable versions of the OpenAPI definition. 42 | * [errors.json](errors.json) is a list of potential global error codes and messages, excluding specific exceptions separately available for each process. 43 | * 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. 44 | * The [extensions](extensions/) folder contains extensions to the openEO API. 45 | 46 | # Development 47 | 48 | The `draft` branch is the latest version and is the one to create Pull Requests against. 49 | 50 | For development some tools can be used: 51 | 52 | 1. Install [node and npm](https://nodejs.org) - should run with any recent version 53 | 2. Run `npm install` in this folder to install the dependencies 54 | 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. 55 | 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. 56 | 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. 57 | -------------------------------------------------------------------------------- /assets/pg-evi-example.json: -------------------------------------------------------------------------------- 1 | { 2 | "dc": { 3 | "process_id": "load_collection", 4 | "description": "Loading the data", 5 | "arguments": { 6 | "id": "Sentinel-2", 7 | "spatial_extent": { 8 | "west": 16.1, 9 | "east": 16.6, 10 | "north": 48.6, 11 | "south": 47.2 12 | }, 13 | "temporal_extent": [ 14 | "2018-01-01", 15 | "2018-02-01" 16 | ], 17 | "bands": [ 18 | "B02", 19 | "B04", 20 | "B08" 21 | ] 22 | } 23 | }, 24 | "evi": { 25 | "process_id": "reduce_dimension", 26 | "description": "Compute the EVI. Formula: 2.5 * (NIR - RED) / (1 + NIR + 6*RED + -7.5*BLUE)", 27 | "arguments": { 28 | "data": { 29 | "from_node": "dc" 30 | }, 31 | "dimension": "bands", 32 | "reducer": { 33 | "process_graph": { 34 | "nir": { 35 | "process_id": "array_element", 36 | "arguments": { 37 | "data": { 38 | "from_parameter": "data" 39 | }, 40 | "label": "B08" 41 | } 42 | }, 43 | "red": { 44 | "process_id": "array_element", 45 | "arguments": { 46 | "data": { 47 | "from_parameter": "data" 48 | }, 49 | "label": "B04" 50 | } 51 | }, 52 | "blue": { 53 | "process_id": "array_element", 54 | "arguments": { 55 | "data": { 56 | "from_parameter": "data" 57 | }, 58 | "label": "B02" 59 | } 60 | }, 61 | "sub": { 62 | "process_id": "subtract", 63 | "arguments": { 64 | "x": { 65 | "from_node": "nir" 66 | }, 67 | "y": { 68 | "from_node": "red" 69 | } 70 | } 71 | }, 72 | "m1": { 73 | "process_id": "multiply", 74 | "arguments": { 75 | "x": 6, 76 | "y": { 77 | "from_node": "red" 78 | } 79 | } 80 | }, 81 | "m2": { 82 | "process_id": "multiply", 83 | "arguments": { 84 | "x": -7.5, 85 | "y": { 86 | "from_node": "blue" 87 | } 88 | } 89 | }, 90 | "sum": { 91 | "process_id": "sum", 92 | "arguments": { 93 | "data": [ 94 | 1, 95 | { 96 | "from_node": "nir" 97 | }, 98 | { 99 | "from_node": "m1" 100 | }, 101 | { 102 | "from_node": "m2" 103 | } 104 | ] 105 | } 106 | }, 107 | "div": { 108 | "process_id": "divide", 109 | "arguments": { 110 | "x": { 111 | "from_node": "sub" 112 | }, 113 | "y": { 114 | "from_node": "sum" 115 | } 116 | } 117 | }, 118 | "m3": { 119 | "process_id": "multiply", 120 | "arguments": { 121 | "x": 2.5, 122 | "y": { 123 | "from_node": "div" 124 | } 125 | }, 126 | "result": true 127 | } 128 | } 129 | } 130 | } 131 | }, 132 | "mintime": { 133 | "process_id": "reduce_dimension", 134 | "description": "Compute a minimum time composite by reducing the temporal dimension", 135 | "arguments": { 136 | "data": { 137 | "from_node": "evi" 138 | }, 139 | "dimension": "t", 140 | "reducer": { 141 | "process_graph": { 142 | "min": { 143 | "process_id": "min", 144 | "arguments": { 145 | "data": { 146 | "from_parameter": "data" 147 | } 148 | }, 149 | "result": true 150 | } 151 | } 152 | } 153 | } 154 | }, 155 | "save": { 156 | "process_id": "save_result", 157 | "arguments": { 158 | "data": { 159 | "from_node": "mintime" 160 | }, 161 | "format": "GTiff" 162 | }, 163 | "result": true 164 | } 165 | } -------------------------------------------------------------------------------- /assets/pg-evi-example.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Open-EO/openeo-api/c5a45b4647b06e313a4f099e9119bfa3cca5c6a3/assets/pg-evi-example.png -------------------------------------------------------------------------------- /assets/pg-schema.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "http://json-schema.org/draft-07/schema#", 3 | "title": "Process Graph", 4 | "description": "A process graph defines a graph-like structure as a connected set of executable processes. Each key is a unique identifier (node id) that is used to refer to the process in the graph. This JSON Schema is provided for convenience and doesn't claim to be complete or correct. The source of truth for the process graph schema is the OpenAPI specification!", 5 | "allOf": [ 6 | { 7 | "$ref": "#/definitions/process_graph" 8 | } 9 | ], 10 | "definitions": { 11 | "process_graph": { 12 | "title": "Process Graph", 13 | "type": "object", 14 | "additionalProperties": { 15 | "$ref": "#/definitions/process_node" 16 | } 17 | }, 18 | "process_node": { 19 | "title": "Process Node", 20 | "type": "object", 21 | "required": [ 22 | "process_id", 23 | "arguments" 24 | ], 25 | "properties": { 26 | "process_id": { 27 | "type": "string", 28 | "pattern": "^\\w+$" 29 | }, 30 | "namespace": { 31 | "type": [ 32 | "string", 33 | "null" 34 | ], 35 | "default": null 36 | }, 37 | "result": { 38 | "type": "boolean", 39 | "default": false 40 | }, 41 | "description": { 42 | "type": [ 43 | "string", 44 | "null" 45 | ] 46 | }, 47 | "arguments": { 48 | "$ref": "#/definitions/process_arguments" 49 | } 50 | } 51 | }, 52 | "process_arguments": { 53 | "title": "Process Arguments", 54 | "type": "object", 55 | "additionalProperties": { 56 | "$ref": "#/definitions/process_argument_value" 57 | } 58 | }, 59 | "process_argument_value": { 60 | "title": "Process Argument Value", 61 | "anyOf": [ 62 | { 63 | "type": "null" 64 | }, 65 | { 66 | "type": "object", 67 | "title": "Object", 68 | "properties": { 69 | "from_parameter": { 70 | "not": {} 71 | }, 72 | "from_node": { 73 | "not": {} 74 | }, 75 | "process_graph": { 76 | "not": {} 77 | } 78 | } 79 | }, 80 | { 81 | "type": "string", 82 | "title": "String" 83 | }, 84 | { 85 | "type": "number", 86 | "title": "Number (incl. integers)" 87 | }, 88 | { 89 | "type": "boolean", 90 | "title": "Boolean" 91 | }, 92 | { 93 | "type": "array", 94 | "title": "Array", 95 | "items": { 96 | "$ref": "#/definitions/process_argument_value" 97 | } 98 | }, 99 | { 100 | "type": "object", 101 | "title": "Result Reference", 102 | "required": [ 103 | "from_node" 104 | ], 105 | "properties": { 106 | "from_node": { 107 | "type": "string" 108 | } 109 | }, 110 | "additionalProperties": false 111 | }, 112 | { 113 | "type": "object", 114 | "title": "Parameter Reference", 115 | "required": [ 116 | "from_parameter" 117 | ], 118 | "properties": { 119 | "from_parameter": { 120 | "type": "string" 121 | } 122 | }, 123 | "additionalProperties": false 124 | }, 125 | { 126 | "type": "object", 127 | "title": "Process Graph", 128 | "required": [ 129 | "process_graph" 130 | ], 131 | "properties": { 132 | "process_graph": { 133 | "$ref": "#/definitions/process_graph" 134 | } 135 | } 136 | } 137 | ] 138 | } 139 | } 140 | } -------------------------------------------------------------------------------- /errors.json: -------------------------------------------------------------------------------- 1 | { 2 | "Internal": { 3 | "description": "An internal server error with a proprietary message.", 4 | "message": "Server error: {message}", 5 | "http": 500, 6 | "tags": [ 7 | "General" 8 | ] 9 | }, 10 | "NotFound": { 11 | "description": "To be used if the requested resource does not exist. Note: There are specialized errors for missing jobs (JobNotFound), files (FileNotFound), etc. Unsupported endpoints MAY send an 'FeatureUnsupported' (501) error.", 12 | "message": "Resource not found.", 13 | "http": 404, 14 | "tags": [ 15 | "General" 16 | ] 17 | }, 18 | "FeatureUnsupported": { 19 | "description": "The back-end responds with this error whenever an endpoint is specified in the openEO API, but is not supported.", 20 | "message": "Feature not supported.", 21 | "http": 501, 22 | "tags": [ 23 | "General" 24 | ] 25 | }, 26 | "InfrastructureMaintenance": { 27 | "description": "Service is currently not available as the infrastructure is currently undergoing maintenance work.", 28 | "message": "Service is not available at the moment due to maintenance work. Please try again later or contact our support.", 29 | "http": 503, 30 | "tags": [ 31 | "General" 32 | ] 33 | }, 34 | "InfrastructureBusy": { 35 | "description": "Service is generally available, but the infrastructure can't handle it at the moment as too many requests are processed.", 36 | "message": "Service is not available at the moment due to overloading. Please try again later or contact our support.", 37 | "http": 503, 38 | "tags": [ 39 | "General" 40 | ] 41 | }, 42 | "UnsupportedApiVersion": { 43 | "description": "The service doesn't support the openEO API version specified in the request URL. Clients should check well-known document for supported versions.", 44 | "message": "The requested API version '{version}' is not supported.", 45 | "http": 404, 46 | "tags": [ 47 | "General" 48 | ] 49 | }, 50 | "RequestTimeout": { 51 | "description": "The request took too long and timed out.", 52 | "message": "Request timed out.", 53 | "http": 408, 54 | "tags": [ 55 | "General", 56 | "Data Processing" 57 | ] 58 | }, 59 | "BudgetInvalid": { 60 | "description": "The budget is too low as it is either smaller than or equal to 0 or below the costs.", 61 | "message": "The specified budget is too low.", 62 | "http": 400, 63 | "tags": [ 64 | "Batch Jobs", 65 | "Secondary Services", 66 | "Data Processing" 67 | ] 68 | }, 69 | "EstimateComplexity": { 70 | "description": "The process is too complex to calculate an estimate, e.g. due to a UDF or other processes that are complex to estimate costs reliably.", 71 | "message": "The process is too complex to calculate an estimate.", 72 | "http": 500, 73 | "tags": [ 74 | "Batch Jobs" 75 | ] 76 | }, 77 | "NoDataForUpdate": { 78 | "description": "For PATCH requests: No valid data specified at all.", 79 | "message": "No data specified to be updated.", 80 | "http": 400, 81 | "tags": [ 82 | "Batch Jobs", 83 | "Secondary Services" 84 | ] 85 | }, 86 | "PropertyNotEditable": { 87 | "description": "For PATCH requests: The specified parameter can't be updated. It is read-only.", 88 | "message": "The specified property '{property}' is read-only.", 89 | "http": 400, 90 | "tags": [ 91 | "Batch Jobs", 92 | "Secondary Services" 93 | ] 94 | }, 95 | "CollectionNotFound": { 96 | "description": "The requested collection does not exist.", 97 | "message": "Collection '{identifier}' does not exist.", 98 | "http": 404, 99 | "tags": [ 100 | "EO Data Discovery" 101 | ] 102 | }, 103 | "StorageFailure": { 104 | "description": "Server couldn't store file(s) due to server-side reasons.", 105 | "message": "Unable to store files due to a server error. Please try again later or contact our support.", 106 | "http": 500, 107 | "tags": [ 108 | "File Management", 109 | "Batch Jobs" 110 | ] 111 | }, 112 | "StorageQuotaExceeded": { 113 | "description": "The storage quota has been exceeded by the user.", 114 | "message": "Your storage quota has been exceeded.", 115 | "http": 400, 116 | "tags": [ 117 | "File Management", 118 | "Batch Jobs" 119 | ] 120 | }, 121 | "FileNotFound": { 122 | "description": "The requested file does not exist.", 123 | "message": "File '{file}' does not exist.", 124 | "http": 404, 125 | "tags": [ 126 | "File Management" 127 | ] 128 | }, 129 | "FilePathInvalid": { 130 | "description": "The specified path is invalid or not accessible. Path could contain invalid characters, point to an existing folder or a location outside of the user folder.", 131 | "message": "File path is invalid: {reason}", 132 | "http": 400, 133 | "tags": [ 134 | "File Management" 135 | ] 136 | }, 137 | "FileOperationUnsupported": { 138 | "description": null, 139 | "message": "The file operation is not supported for the specified path.", 140 | "http": 400, 141 | "tags": [ 142 | "File Management" 143 | ] 144 | }, 145 | "FolderOperationUnsupported": { 146 | "description": "The specified path is a folder and the operation is only supported for files.", 147 | "message": "Operation is only supported for files, not folders.", 148 | "http": 400, 149 | "tags": [ 150 | "File Management" 151 | ] 152 | }, 153 | "ContentTypeInvalid": { 154 | "description": "The specified media (MIME) type used in the Content-Type header is not allowed.", 155 | "message": "The media type is not supported. Allowed: {types}", 156 | "http": 400, 157 | "tags": [ 158 | "File Management", 159 | "General" 160 | ] 161 | }, 162 | "FileTypeInvalid": { 163 | "description": "File format or file extension is not allowed.", 164 | "message": "File format {type} not allowed. Allowed file formats: {types}", 165 | "http": 400, 166 | "tags": [ 167 | "File Management" 168 | ] 169 | }, 170 | "FileSizeExceeded": { 171 | "description": "File exceeds allowed maximum file size.", 172 | "message": "File size it too large. Maximum file size: {size}", 173 | "http": 400, 174 | "tags": [ 175 | "File Management" 176 | ] 177 | }, 178 | "FileContentInvalid": { 179 | "description": "The content of the file is invalid.", 180 | "message": "File content is invalid.", 181 | "http": 400, 182 | "tags": [ 183 | "File Management" 184 | ] 185 | }, 186 | "FileLocked": { 187 | "description": "The file is locked by a running job or another process.", 188 | "message": "File '{file}' is locked by another process.", 189 | "http": 400, 190 | "tags": [ 191 | "File Management" 192 | ] 193 | }, 194 | "ProcessGraphNotFound": { 195 | "description": "The requested user-defined process does not exist. To be used for all endpoints starting with `/process_graphs`.", 196 | "message": "User-defined process '{identifier}' does not exist.", 197 | "http": 404, 198 | "tags": [ 199 | "User-Defined Processes" 200 | ] 201 | }, 202 | "ProcessInvalid": { 203 | "description": "The process given is invalid, which ususlly means that the process metadata is invalid.", 204 | "message": "Invalid process specified.", 205 | "http": 400, 206 | "tags": [ 207 | "User-Defined Processes", 208 | "Batch Jobs", 209 | "Secondary Services", 210 | "Data Processing" 211 | ] 212 | }, 213 | "ProcessGraphMissing": { 214 | "description": "The process doesn't contain a process graph. For jobs, services, and sync. processing the parameter `process` must contain a `process_graph`.", 215 | "message": "Invalid process specified. It doesn't contain a process graph.", 216 | "http": 400, 217 | "tags": [ 218 | "User-Defined Processes", 219 | "Batch Jobs", 220 | "Secondary Services", 221 | "Data Processing" 222 | ] 223 | }, 224 | "ProcessGraphInvalid": { 225 | "description": "The process doesn't contain a valid process graph, which means it doesn't comply to the general structure / schema.", 226 | "message": "Invalid process graph specified.", 227 | "http": 400, 228 | "tags": [ 229 | "User-Defined Processes", 230 | "Batch Jobs", 231 | "Secondary Services", 232 | "Data Processing" 233 | ] 234 | }, 235 | "PredefinedProcessExists": { 236 | "description": "If a user wants to store a user-defined process with the id of a predefined process.", 237 | "message": "A predefined process with the given identifier exists.", 238 | "http": 400, 239 | "tags": [ 240 | "User-Defined Processes" 241 | ] 242 | }, 243 | "ProcessGraphComplexity": { 244 | "description": "The process graph is too complex for synchronous processing and will likely time out. Please use a batch job instead.", 245 | "message": "The process is too complex for for synchronous processing. Please use a batch job instead.", 246 | "http": 400, 247 | "tags": [ 248 | "Data Processing" 249 | ] 250 | }, 251 | "ProcessUnsupported": { 252 | "description": "A process (predefined or user-defined) with the specified identifier is not available. To be used when validating or executing process graphs.", 253 | "message": "Process with identifier '{process}' is not available in namespace '{namespace}'.", 254 | "http": 400, 255 | "tags": [ 256 | "Data Processing" 257 | ] 258 | }, 259 | "ProcessParameterUnsupported": { 260 | "description": null, 261 | "message": "Process '{process}' does not support parameter '{parameter}'.", 262 | "http": 400, 263 | "tags": [ 264 | "Data Processing" 265 | ] 266 | }, 267 | "ProcessParameterInvalid": { 268 | "description": null, 269 | "message": "The value passed for parameter '{parameter}' in process '{process}' is invalid: {reason}", 270 | "http": 400, 271 | "tags": [ 272 | "Data Processing" 273 | ] 274 | }, 275 | "ProcessParameterRequired": { 276 | "description": null, 277 | "message": "Process '{process}' parameter '{parameter}' is required.", 278 | "http": 400, 279 | "tags": [ 280 | "Data Processing" 281 | ] 282 | }, 283 | "JobNotFound": { 284 | "description": "The requested job does not exist.", 285 | "message": "The batch job '{identifier}' does not exist.", 286 | "http": 404, 287 | "tags": [ 288 | "Batch Jobs" 289 | ] 290 | }, 291 | "JobLocked": { 292 | "description": "The job is currently locked due to a running batch computation and can't be modified meanwhile.", 293 | "message": "Batch job is locked due to a queued or running batch computation.", 294 | "http": 400, 295 | "tags": [ 296 | "Batch Jobs" 297 | ] 298 | }, 299 | "JobNotFinished": { 300 | "description": null, 301 | "message": "Batch job has not finished computing the results yet. Please try again later or contact our support.", 302 | "http": 400, 303 | "tags": [ 304 | "Batch Jobs" 305 | ] 306 | }, 307 | "JobNotStarted": { 308 | "description": "Job has not been queued or started yet or was canceled and not restarted by the user.", 309 | "message": "Batch job must be started first.", 310 | "http": 400, 311 | "tags": [ 312 | "Batch Jobs" 313 | ] 314 | }, 315 | "ResultLinkExpired": { 316 | "description": "The signed URLs for batch job results have expired. Please send a request to `GET /jobs/{job_id}/results` to refresh the links.", 317 | "message": "The link to the batch job result has expired. Please request the results again.", 318 | "http": 410, 319 | "tags": [ 320 | "Batch Jobs" 321 | ] 322 | }, 323 | "PaymentRequired": { 324 | "description": "The budget required to fulfil the request is insufficient.", 325 | "message": "The budget required to fulfil the request is not sufficient. A payment is required first.", 326 | "http": 402, 327 | "tags": [ 328 | "Batch Jobs", 329 | "Secondary Services" 330 | ] 331 | }, 332 | "BillingPlanInvalid": { 333 | "description": "The billing plan is not on the list of available plans.", 334 | "message": "The billing plan is invalid.", 335 | "http": 400, 336 | "tags": [ 337 | "Batch Jobs", 338 | "Secondary Services", 339 | "Data Processing" 340 | ] 341 | }, 342 | "BillingPlanMissing": { 343 | "description": "No billing plan has been specified by the user and the billing plan can't be determined unambiguously.", 344 | "message": "A billing plan must be specified.", 345 | "http": 400, 346 | "tags": [ 347 | "Batch Jobs", 348 | "Secondary Services", 349 | "Data Processing" 350 | ] 351 | }, 352 | "AuthenticationRequired": { 353 | "description": "The client did not provide any authentication details for a resource requiring authentication or the provided authentication details are not correct.", 354 | "message": "Unauthorized.", 355 | "http": 401, 356 | "tags": [ 357 | "Account Management" 358 | ] 359 | }, 360 | "AuthenticationSchemeInvalid": { 361 | "description": "Invalid authentication scheme (e.g. Bearer).", 362 | "message": "Authentication method not supported.", 363 | "http": 403, 364 | "tags": [ 365 | "Account Management" 366 | ] 367 | }, 368 | "TokenInvalid": { 369 | "description": null, 370 | "message": "Authorization token has expired or is invalid. Please authenticate again.", 371 | "http": 403, 372 | "tags": [ 373 | "Account Management" 374 | ] 375 | }, 376 | "CredentialsInvalid": { 377 | "description": null, 378 | "message": "Credentials are not correct.", 379 | "http": 403, 380 | "tags": [ 381 | "Account Management" 382 | ] 383 | }, 384 | "PermissionsInsufficient": { 385 | "description": "Forbidden. The client did provided correct authentication details, but the privileges/permissions of the provided credentials do not allow to request the resource.", 386 | "message": "Forbidden. The permissions of the authenticated account do not allow to request the requested resource.", 387 | "http": 403, 388 | "tags": [ 389 | "Account Management" 390 | ] 391 | }, 392 | "ServiceNotFound": { 393 | "description": "The requested secondary service does not exist.", 394 | "message": "Service '{identifier}' does not exist.", 395 | "http": 404, 396 | "tags": [ 397 | "Secondary Services" 398 | ] 399 | }, 400 | "ServiceUnsupported": { 401 | "description": null, 402 | "message": "Service type '{type}' is not supported.", 403 | "http": 400, 404 | "tags": [ 405 | "Secondary Services" 406 | ] 407 | }, 408 | "ServiceConfigUnsupported": { 409 | "description": "Refers to the secondary service `configuration` object.", 410 | "message": "Service parameter '{parameter}' is not supported.", 411 | "http": 400, 412 | "tags": [ 413 | "Secondary Services" 414 | ] 415 | }, 416 | "ServiceConfigInvalid": { 417 | "description": "Refers to the secondary service `configuration` object.", 418 | "message": "The value passed for the service parameter '{parameter}' is invalid: {reason}", 419 | "http": 400, 420 | "tags": [ 421 | "Secondary Services" 422 | ] 423 | }, 424 | "ServiceConfigRequired": { 425 | "description": "Refers to the secondary service `configuration` object.", 426 | "message": "Service parameter '{parameter}' is required.", 427 | "http": 400, 428 | "tags": [ 429 | "Secondary Services" 430 | ] 431 | } 432 | } -------------------------------------------------------------------------------- /extensions/commercial-data/README.md: -------------------------------------------------------------------------------- 1 | # Commercial Data Extension 2 | 3 | The Commercial Data API extension provides an interface for discovering, ordering and using commercial data in the openEO API. 4 | 5 | - Version: **0.1.0** 6 | - Stability: **experimental** 7 | - [OpenAPI document](openapi.yaml) 8 | - Conformance class: `https://api.openeo.org/extensions/commercial-data/0.1.0` 9 | 10 | **Note:** This document only documents the additions to the specification. 11 | Extensions can not change or break existing behavior of the openEO API. 12 | 13 | ## Overview of the workflow 14 | 15 | 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. 16 | 17 | 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. 18 | 19 | The client can then create an order for the desired products from a orderable collection. Because of the financial cost of purchasing the data, a separate endpoint for confirming the execution of that specific order should be implemented. 20 | 21 | When the order is completed, the data is ingested in a collection and its ID is available at `/orders/{order_id}` as `target_collection_id`. The user should be able to access the data using the `target_collection_id` at the temporal and spatial location of the purchased products. 22 | 23 | ### Collection discovery 24 | 25 | 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. 26 | 27 | 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). 28 | 29 | Commercial data collections can include an `order_parameters` field if ordering supports additional parameters that specify how the products should be delivered. 30 | 31 | Commercial data collections must also include human-readable pricing information for searching and ordering the products. If searching the products is free it should be set to `null`. If needed, references to additional information about pricing can be added to `links` with the relation type `pricing_info`. 32 | 33 | #### Example 34 | 35 | ```json 36 | { 37 | "stac_version": "1.0.0", 38 | "stac_extensions": [ 39 | "https://stac-extensions.github.io/datacube/v1.0.0/schema.json", 40 | "https://stac-extensions.github.io/order/v1.0.0/schema.json" 41 | ], 42 | "type": "Collection", 43 | "id": "PLEIADES", 44 | "title": "Airbus Pleiades", 45 | "description": "Pleiades is a satellite constellation providing very high-resolution optical imagery and is owned by Airbus. Pléiades is composed of two twin satellites orbiting the Earth 180° apart. The satellites deliver 0.5 m optical imagery and offer a daily revisit capability to any point on the globe.", 46 | "license": "proprietary", 47 | "providers": [...], 48 | "extent": {...}, 49 | "cube:dimensions": {...}, 50 | "summaries": {...}, 51 | "assets": {...}, 52 | "order:status": "orderable", 53 | "order_parameters": [ 54 | { 55 | "name": "sample_type", 56 | "description": "sample type of the output raster.", 57 | "schema": { 58 | "type": "string", 59 | "enum": [ 60 | "UINT16", 61 | "UINT8" 62 | ] 63 | }, 64 | }, 65 | ], 66 | "pricing": { 67 | "searching": null, 68 | "ordering": { 69 | "description": "Minimum area per order is 0.25 km2. The price is calculated based on a 6-months sliding window.", 70 | } 71 | }, 72 | "links": [ 73 | { 74 | "title": "Airbus Pleiades pricing", 75 | "rel": "pricing_info", 76 | "href": "https://www.sentinel-hub.com/pricing/#tpd_pricing" 77 | }, 78 | ... 79 | ] 80 | } 81 | ``` 82 | 83 | ### Filtering parameters discovery 84 | 85 | 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). 86 | 87 | #### Example 88 | 89 | Example response from `GET /collections/PLEIADES/queryables`: 90 | ```json 91 | { 92 | "$schema":"http://json-schema.org/draft-07/schema#", 93 | "$id":"http://openeo.example/collections/PLEIADES/queryables", 94 | "type":"object", 95 | "title":"Queryables of Airbus Pleiades collection.", 96 | "description":"Available properties for CQL filtering of products.", 97 | "properties":{ 98 | "processing_level":{ 99 | "title":"Processing level", 100 | "description":"Limit search to only Living Library images with 'SENSOR' or access all images with 'ALBUM'.", 101 | "type":"string", 102 | "enum":[ 103 | "SENSOR", 104 | "ALBUM" 105 | ] 106 | }, 107 | "max_snow_coverage":{ 108 | "title":"Maximum snow coverage", 109 | "description":"The maximum allowable snow coverage in percent.", 110 | "type":"number", 111 | "minimum":0, 112 | "maximum":100, 113 | "default":100 114 | }, 115 | "max_incidence_angle":{ 116 | "title":"Maximum incidence angle", 117 | "description":"The maximum allowable incidence angle in degrees.", 118 | "minimum":0, 119 | "maximum":90, 120 | "default":90 121 | } 122 | } 123 | } 124 | ``` 125 | 126 | ### Searching available products 127 | 128 | 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`. 129 | 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. 130 | 131 | #### Example 132 | 133 | Example request payload to `GET /search` for `PLEIADES` products from "Living Library" with no snow coverage. 134 | 135 | ```json 136 | { 137 | "bbox": [3, 15, 4, 16], 138 | "datetime": ["01-01-2022", "01-02-2022"], 139 | "collections": ["PLEIADES"], 140 | "filter": { 141 | "op": "and", 142 | "args": [ 143 | { 144 | "op": "=", 145 | "args": [{"property": "processing_level"}, "SENSOR"] 146 | }, 147 | { 148 | "op": "=", 149 | "args": [{"property": "max_snow_coverage"}, 0] 150 | } 151 | ] 152 | } 153 | } 154 | ``` 155 | 156 | ### Ordering products 157 | 158 | Backends should implement the following endpoints: 159 | 160 | - `GET /orders`: Get a list of all created orders 161 | - `POST /orders`: Create an order 162 | - `GET /orders/{order_id}`: Get full metadata of a specific order 163 | - `POST /orders/{order_id}`: Confirm a created order 164 | 165 | Optionally, they can also implement: 166 | - `DELETE /orders/{order_id}`: Delete an order 167 | 168 | See the [OpenAPI document](openapi.yaml) for details. 169 | 170 | ### Product metadata 171 | 172 | 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}`. 173 | 174 | `/collections/{collection_id}/items/{item_id}` may return an error if the data has not been ingested yet. 175 | 176 | Items should contain links to the respective orders that made them available using relation type `parent_order`. 177 | 178 | ### Payment 179 | 180 | 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. 181 | 182 | ### Example usage with Python client 183 | 184 | Python client could be extented to support commercial data. Here an example of a possible workflow is provided. 185 | 186 | ```python 187 | >>> import openeo 188 | >>> connection = openeo.connect("openeo.sentinel-hub.com") 189 | >>> connection.list_collection_ids(status="orderable") 190 | ["PLEIADES", "SPOT", ...] 191 | ``` 192 | 193 | We can fetch queryables and hold them in a class that validates user's parameters against the schema and constructs the payload. 194 | ```python 195 | >>> pleiades_queryables = connection.get_queryables(collection_id="PLEIADES") 196 | >>> pleiades_queryables.list() 197 | [{'name': 'processing_level', 'type': 'string', 'enum': ['SENSOR', 'ALBUM']}, {'name': 'max_snow_coverage', 'type': 'number', 'minimum': 0, 'maximum': 100, 'default': 100}, {'name': 'max_incidence_angle', 'type': 'number', 'minimum': 0, 'maximum': 90, 'default': 90}] 198 | ``` 199 | 200 | Setting the values. 201 | ```python 202 | >>> pleiades_queryables.set('processing_level', 'SENSOR') 203 | >>> pleiades_queryables.set('max_snow_coverage', 0) 204 | >>> pleiades_queryables.generate_cql_filter() 205 | {'op': 'and', 'args': [{'op': '=', 'args': [{'property': 'processing_level'}, 'SENSOR']}, {'op': '=', 'args': [{'property': 'max_snow_coverage'}, 0]}]} 206 | ``` 207 | 208 | Searching the products: 209 | ```python 210 | >>> connection.search_items(collection_id="PLEIADES", bbox=(1,2,3,4), filter=pleiades_queryables.generate_cql_filter()) 211 | {'type': 'FeatureCollection', 'features': [{'id': 'c8a1f88d-89cf-4933-9118-45e9c1a5df20','type': 'Feature', 'stac_version': '1.0.0', "stac_extensions": ["https://stac-extensions.github.io/projection/v1.0.0/schema.json", "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json", "https://stac-extensions.github.io/processing/v1.1.0/schema.json"], 'geometry': {'type': 'Polygon', 'coordinates': [[[12.36555287044679, 41.94403289260048]], [12.36571746774068, 41.86399361096971], [12.60746759743069, 41.86372776276345], [12.60758647471871, 41.94379931812686], [12.36555287044679, 41.94403289260048]]}, 'properties': {'constellation': 'PHR', 'datetime': '2022-03-21T10:11:15.055Z', 'view:azimuth': 179.9852862071639, 'eo:cloud_cover': 0, 'proj:centroid': {'lat': 41.903935647240964, 'lon': 12.486569672582828}, 'processing:level': 'SENSOR', 'sensorType': 'OPTICAL', 'spectralRange': 'VISIBLE'}, 'assets': {}, 'links': []}, ...], 'links': []} 212 | ``` 213 | 214 | Create and confirm and order: 215 | ```python 216 | >>> order = connection.create_order(collection_id="PLEIADES", products=["c8a1f88d-89cf-4933-9118-45e9c1a5df20"]) 217 | >>> order.costs 218 | 42 219 | >>> order.status 220 | 'orderable' 221 | >>> order.confirm_order() 222 | >>> order.status 223 | 'ordered' 224 | ``` 225 | 226 | When the order has finished, you can process the data as with a normal collection. 227 | 228 | ```python 229 | >>> order = connection.get_order(id="40264b5-c3ae-46f4-a907-0f612d763d97") 230 | >>> order.status 231 | 'succeeded' 232 | >>> pleiades_cube = connection.load_collection(order.target_collection_id) 233 | ``` -------------------------------------------------------------------------------- /extensions/commercial-data/openapi.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.2 2 | info: 3 | title: openEO Commercial Data API extension 4 | version: 0.1.0 5 | description: >- 6 | The Commercial Data API extension provides an interface for discovering, 7 | ordering and using commercial data in the openEO API. 8 | contact: 9 | name: openEO Consortium 10 | url: 'https://openeo.org' 11 | email: openeo.psc@uni-muenster.de 12 | license: 13 | name: Apache 2.0 14 | url: 'http://www.apache.org/licenses/LICENSE-2.0.html' 15 | externalDocs: 16 | url: https://github.com/Open-EO/openeo-api/blob/draft/extensions/federation/README.md 17 | tags: 18 | - name: Orders 19 | description: Management of commercial data orders 20 | servers: 21 | - url: 'https://openeo.example/api/{version}' 22 | description: >- 23 | The URL of the API MAY freely be chosen by the back-end providers. The 24 | path, including API versioning, is a *recommendation* only. Nevertheless, 25 | all servers MUST support HTTPS as the authentication methods are not 26 | secure with HTTP only! 27 | variables: 28 | version: 29 | default: v1 30 | description: >- 31 | API versioning is RECOMMENDED. As the openEO API is following 32 | [SemVer](https://semver.org/) only the MAJOR part of the stable 33 | version numbers (i.e. versions >= 1.0.0) SHOULD be used for API 34 | versioning in the URL. The reason is that backward-incompatible 35 | changes are usually introduced by major changes. Therefore, the 36 | version number in the URL MUST not be used by the clients to detect 37 | the version number of the API. Use the version number returned from 38 | `GET /` instead. 39 | paths: 40 | /orders: 41 | get: 42 | summary: List all commercial data orders 43 | operationId: list-orders 44 | description: |- 45 | Lists all created orders submitted by a user, regardless of the status 46 | or the collection. 47 | 48 | It is **strongly RECOMMENDED** to keep the response size small by 49 | omitting all optional non-scalar values from objects in `orders` (e.g. `parameters`). 50 | To get the full metadata for an order clients MUST request `GET /orders/{order_id}`. 51 | tags: 52 | - Orders 53 | security: 54 | - Bearer: [] 55 | parameters: 56 | - $ref: '../../openapi.yaml#/components/parameters/pagination_limit' 57 | responses: 58 | '200': 59 | description: List of orders and related links. 60 | content: 61 | application/json: 62 | schema: 63 | title: Orders 64 | type: object 65 | required: 66 | - orders 67 | - links 68 | properties: 69 | orders: 70 | type: array 71 | items: 72 | $ref: '#/components/schemas/order' 73 | links: 74 | $ref: '../../openapi.yaml#/components/schemas/links_pagination' 75 | 4XX: 76 | $ref: '../../openapi.yaml#/components/responses/client_error_auth' 77 | 5XX: 78 | $ref: '../../openapi.yaml#/components/responses/server_error' 79 | post: 80 | summary: Create a new order 81 | operationId: create-order 82 | description: |- 83 | Create an order for selected items (products). 84 | 85 | When an order is created through through this endpoint, the data isn't yet ordered from the commercial data provider. The client MUST explicitly confirm the order through `POST /orders/{order_id}` whereupon the order is executed. 86 | 87 | The order can contain additional parameters that specify how the items should be delivered. 88 | For example, it might be possible to set the projection, resampling method, bit depth etc. of the delivered data. 89 | 90 | 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). 91 | 92 | Returns `Location` and `OpenEO-Identifier` header with the link to the detailed information about the order. 93 | tags: 94 | - Orders 95 | security: 96 | - Bearer: [] 97 | requestBody: 98 | required: true 99 | content: 100 | application/json: 101 | schema: 102 | type: object 103 | required: 104 | - source_collection_id 105 | - items 106 | - parameters 107 | properties: 108 | source_collection_id: 109 | type: string 110 | description: Unique identifier of the collection. 111 | items: 112 | type: array 113 | description: Array of items IDs to order. 114 | items: 115 | $ref: '#/components/schemas/order_id' 116 | parameters: 117 | $ref: '#/components/schemas/order_parameters' 118 | responses: 119 | '201': 120 | description: The order has been created successfully. 121 | headers: 122 | Location: 123 | required: true 124 | schema: 125 | description: |- 126 | Absolute URL to the newly created order. 127 | 128 | The URL points to the metadata endpoint 129 | `GET /orders/{order_id}` with the `{order_id}` being the 130 | unique identifier (ID) of the created order. 131 | format: uri 132 | type: string 133 | example: 'https://openeo.example/api/v1/orders/40264b5-c3ae-46f4-a907-0f612d763d97' 134 | OpenEO-Identifier: 135 | required: true 136 | schema: 137 | $ref: '#/components/schemas/order_id' 138 | 4XX: 139 | $ref: '../../openapi.yaml#/components/responses/client_error_auth' 140 | 5XX: 141 | $ref: '../../openapi.yaml#/components/responses/server_error' 142 | '/orders/{order_id}': 143 | parameters: 144 | - $ref: '#/components/parameters/order_id' 145 | get: 146 | summary: Full metadata for an order 147 | operationId: describe-order 148 | description: |- 149 | Get full metadata of the order. 150 | 151 | 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}`. 152 | tags: 153 | - Orders 154 | security: 155 | - Bearer: [] 156 | responses: 157 | '200': 158 | description: Full order information. 159 | content: 160 | application/json: 161 | schema: 162 | allOf: 163 | - $ref: '#/components/schemas/order' 164 | - type: object 165 | required: 166 | - items 167 | 4XX: 168 | $ref: '../../openapi.yaml#/components/responses/client_error_auth' 169 | 5XX: 170 | $ref: '../../openapi.yaml#/components/responses/server_error' 171 | post: 172 | summary: Confirm an order 173 | operationId: confirm-order 174 | description: |- 175 | Confirm the order, execute the purchase and ingest the data into a target collection. 176 | 177 | 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. 178 | 179 | 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. 180 | 181 | This endpoint only has an effect if `order:status` is `orderable`. 182 | 183 | If the user doesn't have sufficient funds, the endpoint should return an error and `order:status` should not change. 184 | 185 | Otherwise, the `order:status` changes from `orderable` to `ordered` until a new order status (e.g. `succeeded` or `failed`) becomes available. 186 | tags: 187 | - Orders 188 | security: 189 | - Bearer: [] 190 | responses: 191 | '202': 192 | description: The order has been confirmed successfully. 193 | 4XX: 194 | $ref: '../../openapi.yaml#/components/responses/client_error_auth' 195 | 5XX: 196 | $ref: '../../openapi.yaml#/components/responses/server_error' 197 | delete: 198 | summary: Delete an order 199 | operationId: delete-order 200 | description: |- 201 | Removes the order and all ordered items from the back-ends. 202 | 203 | If an order is still in progress, it cancels the order. 204 | Costs MAY still occur. 205 | tags: 206 | - Orders 207 | security: 208 | - Bearer: [] 209 | responses: 210 | '204': 211 | description: The order and data has been successfully deleted. 212 | 4XX: 213 | $ref: '../../openapi.yaml#/components/responses/client_error_auth' 214 | 5XX: 215 | $ref: '../../openapi.yaml#/components/responses/server_error' 216 | components: 217 | schemas: 218 | order_id: 219 | type: string 220 | description: >- 221 | Unique identifier of the order at the back-end, which MUST match the specified pattern. 222 | pattern: '^[\w\-\.~]+$' 223 | example: fb6799ab 224 | item_id: 225 | type: string 226 | description: >- 227 | Unique identifier of the item. Must be unique within a collection. 228 | example: c8a1f88d-89cf-4933-9118-45e9c1a5df20 229 | order_parameters: 230 | type: object 231 | description: >- 232 | Key-value pairs of available `order_parameters` as listed at 233 | `GET /collections/{collection_id}` for filtering available items. 234 | additionalProperties: 235 | x-additionalPropertiesName: Order Parameter Name 236 | description: Value of the order parameter for the request. 237 | example: 238 | resamplingKernel: 'NN' 239 | order: 240 | type: object 241 | title: Order 242 | description: >- 243 | Information about an order. 244 | 245 | The properties with the `order:` prefix follow the fields defined in the 246 | [STAC Order Extension](https://github.com/stac-extensions/order/tree/v1.0.0). 247 | required: 248 | - id 249 | - order:status 250 | - order:date 251 | - source_collection_id 252 | - target_collection_id 253 | - costs 254 | properties: 255 | id: 256 | $ref: '#/components/schemas/order_id' 257 | order:id: 258 | type: string 259 | description: >- 260 | Identifier of the order at the data provider. 261 | example: 40264b5-c3ae-46f4-a907-0f612d763d97 262 | order:status: 263 | type: string 264 | description: |- 265 | The status of the order. 266 | * `orderable`: The item or asset is orderable via the provider scenario. 267 | * `ordered`: The item or asset is ordered and the provider is preparing to make it available. 268 | * `pending`: The item or asset is ordered but wait for an activation before being able for shipping. 269 | * `shipping` The item or asset order are being processed by the provider to provide you with the asset(s). 270 | * `succeeded`: The provider has delivered your order and asset(s) are available. 271 | * `failed`: The provider is not able to deliver the order. 272 | * `canceled` The order has been canceled. 273 | enum: 274 | - orderable 275 | - ordered 276 | - pending 277 | - shipping 278 | - succeeded 279 | - failed 280 | - canceled 281 | order:date: 282 | type: string 283 | format: date-time 284 | description: The order time. Formatted as a 285 | [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. 286 | example: '2017-01-01T09:32:12Z' 287 | order:expiration_date: 288 | type: string 289 | format: date-time 290 | description: The validity time of the order. Formatted as a 291 | [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) date-time. 292 | example: '2999-01-01T00:00:00Z' 293 | source_collection_id: 294 | type: string 295 | description: Unique identifier of the source collection. 296 | pattern: '^[\w\-\.~\/]+$' 297 | example: 'PLEIADES' 298 | target_collection_id: 299 | type: string 300 | description: >- 301 | Unique identifier of the target collection. 302 | Can be the same as `source_collection_id`. 303 | pattern: '^[\w\-\.~\/]+$' 304 | example: 'PLEIADES' 305 | costs: 306 | $ref: '../../openapi.yaml#/components/schemas/money' 307 | parameters: 308 | $ref: '#/components/schemas/order_parameters' 309 | items: 310 | type: array 311 | description: List of ordered item IDs. 312 | items: 313 | $ref: '#/components/schemas/item_id' 314 | links: 315 | type: array 316 | description: |- 317 | Links related to this order, e.g. to metadata for ordered items 318 | listed in `items`. 319 | 320 | It is highly RECOMMENDED to provide links with the 321 | following `rel` (relation) types: 322 | 323 | 1. `item`: A link back to a valid STAC Item that has been ordered. 324 | Could be a link to `GET /collections/{collection_id}/items/{item_id}`. 325 | 326 | 2. `order`: A link pointing to a dcoument describing the ordering 327 | terms and conditions of the data provider. 328 | 329 | For additional relation types see also the lists of 330 | [common relation types in openEO](#section/API-Principles/Web-Linking). 331 | items: 332 | $ref: '../../openapi.yaml#/components/schemas/link' 333 | parameters: 334 | order_id: 335 | name: order_id 336 | in: path 337 | description: >- 338 | Unique identifier of an order. 339 | 340 | This corresponds to the `id` property of an order. 341 | required: true 342 | schema: 343 | $ref: '#/components/schemas/order_id' 344 | securitySchemes: 345 | Bearer: 346 | type: http 347 | scheme: bearer 348 | bearerFormat: >- 349 | The Bearer Token MUST consist of the authentication method, a provider 350 | ID (if available) and the token itself. All separated by a forward slash 351 | `/`. Examples (replace `TOKEN` with the actual access token): (1) Basic 352 | authentication (no provider ID available): `basic//TOKEN` (2) OpenID 353 | Connect (provider ID is `ms`): `oidc/ms/TOKEN`. For OpenID Connect, the 354 | provider ID corresponds to the value specified for `id` for each 355 | provider in `GET /credentials/oidc`. 356 | Basic: 357 | type: http 358 | scheme: basic 359 | -------------------------------------------------------------------------------- /extensions/commercial-data/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@openeo/api-extension-commercial-data", 3 | "version": "0.1.0", 4 | "author": "openEO Consortium", 5 | "license": "Apache-2.0", 6 | "description": "The openEO API specification.", 7 | "homepage": "https://openeo.org", 8 | "bugs": { 9 | "url": "https://github.com/Open-EO/openeo-api/issues" 10 | }, 11 | "repository": { 12 | "type": "git", 13 | "url": "git+https://github.com/Open-EO/openeo-api.git" 14 | }, 15 | "devDependencies": { 16 | "@stoplight/spectral": "^5.9.1", 17 | "redoc-cli": "^0.13.18" 18 | }, 19 | "scripts": { 20 | "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", 21 | "build": "redoc-cli bundle openapi.yaml -o redoc.html --title \"openEO API\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", 22 | "test": "spectral lint openapi.yaml" 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /extensions/federation/README.md: -------------------------------------------------------------------------------- 1 | # Federation Extension 2 | 3 | The openEO API is a specification for interoperable cloud-based processing of large Earth observation datasets. 4 | 5 | This is an extension for federation aspects, i.e. where multiple back-ends are exposed as a single API. 6 | 7 | - Version: **0.1.0** 8 | - Stability: **experimental** 9 | - Conformance class: `https://api.openeo.org/extensions/federation/0.1.0` 10 | 11 | **Note:** This document only documents the additions to the specification. 12 | Extensions can not change or break existing behavior of the openEO API. 13 | 14 | ## Backend details 15 | 16 | A new required field `federation` is added to `GET /` to enable federation. 17 | 18 | ### OpenAPI fragment 19 | 20 | ```yaml 21 | schema: 22 | type: object 23 | required: 24 | - 'federation' 25 | properties: 26 | 'federation': 27 | description: >- 28 | Lists all back-ends that are part of this federation with details. 29 | They keys of the object are the unique identifiers for the back-ends that are returned in sub-sequent requests (see below). 30 | type: object 31 | minProperties: 2 32 | additionalProperties: 33 | type: object 34 | required: 35 | - url 36 | properties: 37 | url: 38 | type: string 39 | format: uri 40 | description: >- 41 | URL to the versioned API endpoint of the back-end, 42 | so a URL that is available through well-known discovery on the back-end. 43 | example: https://openeo.provider.org/api/v1/ 44 | title: 45 | type: string 46 | description: Name of the back-end. 47 | description: 48 | type: string 49 | description: A description of the back-end and its specifics. 50 | status: 51 | type: string 52 | enum: 53 | - online 54 | - offline 55 | description: Current status of the back-ends. 56 | default: online 57 | last_status_check: 58 | type: string 59 | format: date-time 60 | description: The time at which the status of the back-end was checked last. 61 | last_successful_check: 62 | type: string 63 | format: date-time 64 | description: >- 65 | If the `status` is `offline`: The time at which the back-end was checked and available the last time. 66 | Otherwise, this is equal to the property `last_status_check`. 67 | experimental: 68 | type: boolean 69 | description: >- 70 | Declares the back-end to be experimental, which means that 71 | it is likely to change or may produce unpredictable behaviour. 72 | default: false 73 | deprecated: 74 | type: boolean 75 | description: |- 76 | Declares the back-end to be deprecated with the potential 77 | to be removed in any of the next versions. 78 | default: false 79 | ``` 80 | 81 | ### Example 82 | 83 | ```json 84 | { 85 | "api_version": "1.2.0", 86 | "federation": { 87 | "vito": { 88 | "title": "VITO", 89 | "url": "https://openeo.vito.be" 90 | }, 91 | "eodc": { 92 | "title": "EODC", 93 | "url": "https://openeo.eodc.eu" 94 | }, 95 | "wwu": { 96 | "title": "WWU Münster", 97 | "url": "https://openeo.wwu.de", 98 | "status": "offline", 99 | "description": "Experimental integration of the WWU HPC", 100 | "experimental": true 101 | } 102 | }, 103 | ... 104 | } 105 | ``` 106 | 107 | ## Lists of resources 108 | 109 | Clients will assume that all lists of resources are the a combination of all back-ends listed in `GET /`. 110 | Federated APIs can expose if any of the back-ends is not available and thus is not part of the response. 111 | 112 | Applies to: 113 | 114 | - `GET /collections` 115 | - `GET /processes` 116 | - `GET /file_formats` 117 | - `GET /process_graphs` 118 | - `GET /jobs` 119 | - `GET /jobs/{job_id}` 120 | - `GET /jobs/{job_id}/results` 121 | - `GET /services` 122 | 123 | The following endpoints define the resources (UDF runtimes / service types) at the top level of their response as key-value pairs. 124 | Consequently, they are not extensible with additional properties for federation purposes. 125 | 126 | - `GET /udf_runtimes` 127 | - `GET /service_types` 128 | 129 | ### OpenAPI fragment 130 | 131 | ```yaml 132 | schema: 133 | type: object 134 | properties: 135 | 'federation:missing': 136 | description: >- 137 | Lists all back-ends that were not considered in the response (e.g. because they were not accessible). 138 | If not given or empty, all back-ends were considered for creating the response. 139 | Back-ends that were listed as offline in the capabilities still need to be listed here. 140 | type: array 141 | items: 142 | type: string 143 | description: The ID of a back-end. 144 | ``` 145 | 146 | ### Example 147 | 148 | ```json 149 | { 150 | "federation:missing": ["wwu"], 151 | "collections": [...], 152 | "links": [...] 153 | } 154 | ``` 155 | 156 | ## Resources supported only by a subset of back-ends 157 | 158 | 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. 159 | This can also be embeded deeply into a hierarchical structure, e.g. for process or file format parameters. 160 | 161 | ```yaml 162 | schema: 163 | type: object 164 | properties: 165 | 'federation:backends': 166 | description: >- 167 | Lists all back-ends that support or host the resource. 168 | If not given, all back-ends support the resource. 169 | type: array 170 | minItems: 1 171 | items: 172 | type: string 173 | description: The ID of a back-end. 174 | ``` 175 | 176 | **Note:** In Collections this should generally be provided on the top-level of the object. 177 | 178 | ### Examples 179 | 180 | #### Process 181 | 182 | ```json 183 | { 184 | "process_id": "example", 185 | "federation:backends": ["vito", "eodc"], 186 | "parameters": [ 187 | { 188 | "name": "parameter1", 189 | "description": "A parameter supported by both back-ends...", 190 | "schema": {} 191 | }, 192 | { 193 | "name": "proprietary_parameter", 194 | "description": "A parameter supported only by EODC.", 195 | "federation:backends": ["eodc"], 196 | "schema": {} 197 | } 198 | ] 199 | ... 200 | } 201 | ``` 202 | 203 | #### Collection 204 | 205 | ```json 206 | { 207 | "stac_version": "1.0.0", 208 | "id": "example", 209 | "description": "...", 210 | "summaries": { 211 | "federation:backends": ["vito", "eodc"], 212 | ... 213 | }, 214 | ... 215 | } 216 | ``` -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@openeo/api", 3 | "version": "1.2.0", 4 | "author": "openEO Consortium", 5 | "license": "Apache-2.0", 6 | "description": "The openEO API specification.", 7 | "homepage": "https://openeo.org", 8 | "bugs": { 9 | "url": "https://github.com/Open-EO/openeo-api/issues" 10 | }, 11 | "repository": { 12 | "type": "git", 13 | "url": "git+https://github.com/Open-EO/openeo-api.git" 14 | }, 15 | "devDependencies": { 16 | "@stoplight/spectral-cli": "^6.6.0", 17 | "redoc-cli": "^0.13.18" 18 | }, 19 | "scripts": { 20 | "start": "redoc-cli serve openapi.yaml --watch --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", 21 | "build": "redoc-cli build openapi.yaml -o redoc.html --title \"openEO API\" --cdn --options.expandResponses \"200,201,202,203,204\" --options.pathInMiddlePanel true", 22 | "test": "spectral lint openapi.yaml" 23 | } 24 | } 25 | --------------------------------------------------------------------------------