Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
112 commits
Select commit Hold shift + click to select a range
14050fc
Fixed errors.json #394, #395
m-mohr May 18, 2021
6ce6282
Fixed the default value for the version number in the API url #393
m-mohr May 18, 2021
72f0b05
Fixed the Collection example to use `gsd` instead of `eo:gsd`. #399
m-mohr Jun 4, 2021
ac1351e
Update stac-spec to 1.0.0
m-mohr Jun 4, 2021
d8e58f5
`GET /jobs/{job_id}/results`: Recommendation to add a link with relat…
m-mohr Jun 4, 2021
5a7a320
Clarified error.json, added new error codes
m-mohr Jun 29, 2021
f065286
Merge pull request #403 from Open-EO/error-json
m-mohr Jun 29, 2021
a507f6f
Merge pull request #400 from Open-EO/issue-397
m-mohr Jun 29, 2021
af13c63
"stac_version" example has value "string" #406
m-mohr Jul 8, 2021
07117cc
STAC data cube version number update in examples
m-mohr Jul 26, 2021
b5a73fc
Clarify user_id, add relation types for registration, password recove…
m-mohr Jul 27, 2021
9d95822
Allow the relation type `canonical` to be used generally for resource…
m-mohr Jul 27, 2021
66b7483
pre-defined => predefined, backend => back-end
m-mohr Aug 17, 2021
36dfcb1
Move canonical references to the right place...
m-mohr Aug 18, 2021
2e6d17e
Recommendation for UDF runtime names. #409
m-mohr Aug 19, 2021
5a6dfd2
OIDC: Allow auth code flow and device flow (both without PKCE) as gra…
m-mohr Aug 25, 2021
e171f0d
Merge pull request #411 from Open-EO/issue-410
m-mohr Aug 25, 2021
05a2827
Add first draft for federation extension
m-mohr Oct 19, 2021
1ba501b
Clarify Collection placement and changed naming.
m-mohr Oct 19, 2021
592e266
Relax requirement to use HTTP 501 #415 (#418)
m-mohr Oct 22, 2021
9c57dfa
Clarify currency description #421
m-mohr Oct 28, 2021
59b4bab
`GET /`: Removed the superfluous default value for `currency`. #423
m-mohr Oct 28, 2021
42e963b
Improvements from code-review
m-mohr Oct 28, 2021
ce41e2d
Add federation:description
m-mohr Oct 28, 2021
85d558e
`GET /`: Removed the superfluous default value for `currency`. #423 (…
m-mohr Oct 29, 2021
e0f1c83
Clarify: Send token to discovery endpoints #416 (#417)
m-mohr Nov 2, 2021
034329d
Make the web service parameter example a little less cumbersome from …
m-mohr Nov 17, 2021
c0855ce
Upgrade CI
m-mohr Nov 24, 2021
3582c31
Fix typo in CHANGELOG
m-mohr Nov 29, 2021
f232fec
Logs: Add data processing parameter for minimum severity #329 (#431)
m-mohr Dec 8, 2021
18d638f
Explicitly specify metadata filters for collections #396 (#434)
m-mohr Dec 8, 2021
7d7292d
Support partial/incomplete batch job results #430 (#433)
m-mohr Dec 9, 2021
4a7ed26
STAC: reference_system in cube:dimensions oudated #435
m-mohr Dec 15, 2021
a46fe24
Clarify (default) billing plans (#428)
m-mohr Dec 15, 2021
220e8a3
Clarify that clients may add additional scopes https://github.com/Ope…
m-mohr Jan 11, 2022
3b6e596
Add development notes
m-mohr Jan 13, 2022
a886c8f
Clarify scalar
m-mohr Feb 4, 2022
5a048b5
Remvoe federation:description
m-mohr Feb 7, 2022
91d24b8
Improvements for federation extension
m-mohr Feb 8, 2022
818fb9f
Updates
m-mohr Feb 8, 2022
8ee1dd0
Merge branch 'draft' into federation-extension
m-mohr Feb 8, 2022
0533f9e
Merge pull request #419 from Open-EO/federation-extension
m-mohr Feb 8, 2022
8c24b1f
Update broken links to file format GDAL codes (#439)
soxofaan Feb 17, 2022
0d6ba69
Update broken links to some GDAL drivers (#440)
soxofaan Feb 18, 2022
2e407f5
Clarify data cube link in stac_extensions
m-mohr Mar 1, 2022
8467193
Clarify case-insensitivity of HTTP headers
m-mohr Apr 4, 2022
53a9c2d
Fix typo for Collection Assets #446
m-mohr Apr 19, 2022
f55f8d2
Add documentation for GET /commercial_data/collections/{collection_id…
janjezersek May 3, 2022
2c21fad
Add documentation for GET /commercial_data/search endpoint: searching…
janjezersek May 3, 2022
33ad759
Add documentation for POST /commercial_data/orders endpoint: order pr…
janjezersek May 4, 2022
7be50b0
Add documentation for POST /commercial_data/orders/{order_id} endpoin…
janjezersek May 4, 2022
27a806c
Add documentation for GET /commercial_data/orders endpoint: List all …
janjezersek May 4, 2022
83224f5
Add documentation for GET /commercial_data/orders/{order_id} endpoint…
janjezersek May 4, 2022
697ca66
Cleanup, move STAC item to components.
janjezersek May 4, 2022
ccd3b85
Add a brief description of commercial data.
janjezersek May 4, 2022
2dfc979
Fix issues with request parameters not being defined and missing requ…
janjezersek May 4, 2022
e618e10
Small clarification for the endpoints in GET /
m-mohr Jun 2, 2022
2d9b4e5
Change provider to use STAC Provider field.
janjezersek Jun 20, 2022
8c37ad4
Align Commercial data order with STAC extension 'order'.
janjezersek Jun 20, 2022
8d7f364
Align searching commercial data products with STAC /search.
janjezersek Jun 21, 2022
5bd050f
Add /commercial_data/{collection_id}/queryables endpoint. Fix request…
janjezersek Jun 21, 2022
a842427
Fix linting issues.
janjezersek Jun 22, 2022
4cec5e6
Revert commits f55f8d2265985ae0e5ce060f580f8555327fe0e2, 2c21fad21249…
janjezersek Jul 19, 2022
863fc78
Clarified uniqueness constraints for identifiers. #454
m-mohr Jul 19, 2022
fe4a563
Clarified uniqueness constraints for PG identifiers. #449
m-mohr Jul 19, 2022
4aa5980
Add README for Commercial Data extension.
janjezersek Jul 19, 2022
13b0542
* Make sure stac_version is listed as 1.0.0
janjezersek Jul 21, 2022
fab174c
Make example results more STAC-compliant. Fix schema. Use relation ty…
janjezersek Jul 29, 2022
b3516aa
Use correct identifier for STAC extension schemas, clarify products s…
janjezersek Aug 1, 2022
7724b18
Several improvements for estimates, budget and costs #443 (#458)
m-mohr Aug 1, 2022
24956b3
Clarify the message field in logs (#457)
m-mohr Aug 2, 2022
3c15398
Update redoc-cli
m-mohr Aug 2, 2022
fe93a60
* Change response for POST /orders to be more similar to other openEO…
janjezersek Aug 4, 2022
f21193f
Fix Order schema. Change order id reference to something more importa…
janjezersek Aug 4, 2022
5254f23
Add OpenAPI document for the /orders and /orders/{order_id} endpoints.
janjezersek Aug 4, 2022
ea237fd
Update redoc-cli
m-mohr Aug 15, 2022
ca30724
Align with openEO and STAC, improve docs etc
m-mohr Aug 15, 2022
fb7bc3f
Rename folder
m-mohr Aug 15, 2022
e8db5ff
Merge remote-tracking branch 'origin/draft' into feature/commercial-data
m-mohr Aug 15, 2022
2cf38d8
Move to correct folder
m-mohr Aug 15, 2022
636f632
Add to README and CHANGELOG
m-mohr Aug 15, 2022
086bd37
Clarification
m-mohr Aug 15, 2022
4ce58e4
Update order:status values to match released version, fix links to ST…
janjezersek Aug 18, 2022
8a91f69
Change 'STAC Order specification' to 'STAC Order extension' for consi…
janjezersek Aug 29, 2022
e97ccf4
Merge pull request #447 from Open-EO/feature/commercial-data
Ardweaden Aug 29, 2022
6e79b8f
Clarify the user-defined processes #464
m-mohr Nov 2, 2022
932c736
Upgrade to Spectral v6 (#432)
m-mohr Nov 2, 2022
3034cdf
`GET /jobs` and `GET /jobs/{job_id}`: Added a links property that can…
m-mohr Nov 2, 2022
be6e962
Remove openeo:property_filters again #396
m-mohr Nov 2, 2022
1790f3e
Clarify that logs should be sorted by time.
m-mohr Nov 3, 2022
77a0cb3
Clarify that UTF-8 is the default charset #462 (#466)
m-mohr Nov 7, 2022
d018e4b
Clarify how the well-known document works #460 (#467)
m-mohr Nov 10, 2022
150bef4
Clearly describe that you can add additional properties to requests
m-mohr Nov 15, 2022
65d3f58
Conformance classes / OGC API and STAC API alignment (#468)
m-mohr Nov 16, 2022
8a112b7
Update collection summaries to 1.0.0 #469
m-mohr Nov 17, 2022
ddccbfd
Add "pointcloud" to the gis_data_types #475
m-mohr Dec 9, 2022
926fb55
Clarify that `enabled` is required by removing the default value. #47…
m-mohr Jan 4, 2023
749bfc7
Vector data cubes (#441)
m-mohr Jan 30, 2023
6da0195
Update name of the geometries dimension #479
m-mohr Mar 10, 2023
d72b347
Update CI
m-mohr Mar 30, 2023
b7398b3
Fix batch job result summary #482
m-mohr Mar 30, 2023
c3f8512
Fixed broken STAC (internal) link #486
m-mohr Apr 4, 2023
47ae322
Explicitly specify metadata filters for collections through queryable…
m-mohr Apr 11, 2023
380a756
Add minimum log_level parameter for GET /../logs #485 (#488)
m-mohr Apr 18, 2023
2370307
Better example (openeo) domains #489 and minor clean-up
m-mohr Apr 18, 2023
9fcebd1
Add experimental and deprecated to back-ends in federation extension …
m-mohr May 2, 2023
b2dd2fa
Update conformance classes #186
m-mohr May 3, 2023
34ae614
Update STAC references #469
m-mohr May 3, 2023
f47c072
Clarified ambiguous batch job status changes (#444)
m-mohr May 3, 2023
a98c588
Update version number to v1.2.0
m-mohr May 3, 2023
091af70
Merge remote-tracking branch 'origin/draft' into draft
m-mohr May 3, 2023
3341922
Update version number to v1.2.0
m-mohr May 3, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,10 @@ jobs:
steps:
- name: Inject env variables
uses: rlespinasse/[email protected]
- uses: actions/setup-node@v1
- uses: actions/setup-node@v3
with:
node-version: '16'
- uses: actions/checkout@v2
node-version: 'lts/*'
- uses: actions/checkout@v3
- run: |
npm install
npm run build
Expand Down
9 changes: 4 additions & 5 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,11 @@ on: [push, pull_request]
jobs:
deploy:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [14.x]
steps:
- uses: actions/setup-node@v1
- uses: actions/checkout@v2
- uses: actions/setup-node@v3
with:
node-version: 'lts/*'
- uses: actions/checkout@v3
- name: Run tests
run: |
npm install
Expand Down
20 changes: 4 additions & 16 deletions .spectral.yml
Original file line number Diff line number Diff line change
@@ -1,27 +1,15 @@
extends: "spectral:oas"
# don't error on circular schemas, these are currently not supported by spectral
# https://github.com/stoplightio/spectral/issues/894
# Work around broken rules: https://github.com/stoplightio/spectral/issues/1972
except:
"openapi.yaml#/components/schemas/process_graph/example":
"openapi.yaml#/paths/~1udf_runtimes/get/responses/200/content/application~1json/example":
- oas3-valid-schema-example
"openapi.yaml#/paths/~1processes/get/responses/200/content/application~1json/example":
- oas3-valid-oas-content-example
"openapi.yaml#/paths/~1process_graphs/get/responses/200/content/application~1json/example":
- oas3-valid-oas-content-example
"openapi.yaml#/paths/~1service_types/get/responses/200/content/application~1json/example":
- oas3-valid-oas-content-example
"openapi.yaml#/paths/~1file_formats/get/responses/200/content/application~1json/example":
- oas3-valid-oas-content-example
rules:
# Ported from Spectral 4.0
contact-properties: true
tag-description: true
oas3-parameter-description: true
oas3-unused-components-schema: false # Broken: https://github.com/stoplightio/spectral/issues/1271
oas3-unused-component: false # Broken: https://github.com/stoplightio/spectral/issues/1271
operation-summary-formatted:
description: Operation `summary` should start with upper case and not end with a dot.
recommended: true
type: style
given: '$.paths.*[?( @property === ''get'' || @property === ''put'' || @property === ''post'' || @property === ''delete'' || @property === ''options'' || @property === ''head'' || @property === ''patch'' || @property === ''trace'' )]'
then:
field: summary
Expand All @@ -31,7 +19,7 @@ rules:
tags:
- operation
operation-id-kebab-case:
given: "$"
given: "$..operationId"
then:
function: pattern
functionOptions:
Expand Down
71 changes: 67 additions & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## Unreleased / Draft

## [1.2.0] - 2021-05-31

### Added

- **New extensions:**
- [Commercial Data Extension](./extensions/commercial-data/README.md)
- [Federation Extension](./extensions/federation/README.md)
- `GET /`: New Relation types: [#404](https://github.com/Open-EO/openeo-api/issues/404)
- `create-form` to link to the registration page
- `recovery-form` to link to the credentials recovery page.
- `GET /file_formats`: Add `pointcloud` to the `gis_data_types`. [#475](https://github.com/Open-EO/openeo-api/issues/475)
- `GET /me`: New Relation types `alternate` and `related` for user-specific external pages. [#404](https://github.com/Open-EO/openeo-api/issues/404)
- `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)
- `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)
- `GET /jobs/{job_id}/results`:
- Recommendation to add a link with relation type `canonical` which points to a signed URL with the same content as the response. [#397](https://github.com/Open-EO/openeo-api/issues/397)
- Added metadata field `openeo:status` to indicate the job status (and whether the result is complete or not).
- Added parameter `partial` to allow retrieving incomplete results, which must also add the new property `openeo:status` to the metadata. [#430](https://github.com/Open-EO/openeo-api/issues/430)
- `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs`: Added `level` parameter to requests to set the minimum log level returned by the response. [#485](https://github.com/Open-EO/openeo-api/issues/485)
- Added property `log_level` to secondary web service, batch job and synchronous processing endpoints to indicate the minimum severity level that should be stored for logs. [#329](https://github.com/Open-EO/openeo-api/issues/329)
- `GET /jobs/{job_id}/logs`, `GET /services/{service_id}/logs` and `POST /result`: Added `level` property in responses to reflect the minimum log level that may appear in the response. [#329](https://github.com/Open-EO/openeo-api/issues/329)
- Recommendation to add media types and titles to links for a better user experience.
- Allow the relation type `canonical` to be used generally for (shared) resources (e.g. UDPs or batch jobs) without requiring Bearer authentication. [#405](https://github.com/Open-EO/openeo-api/issues/405)
- Recommendation for UDF runtime names. [#409](https://github.com/Open-EO/openeo-api/issues/409)
- Processes: Added `dimensions` schema for subtype `datacube`
- Collections: Added `geometry` dimension type to `cube:dimensions`
- 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)

### Changed

- 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.
- `cube:dimensions`: `reference_system` is allowed to be PROJJSON, too.
- 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)
- Minimum value for `costs` and `budget` is 0.
- `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)
- 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)

### Fixed

- Explicitly mention the use of HTTP content negotiation
- Clarify that the default charset is UTF-8 [#462](https://github.com/Open-EO/openeo-api/issues/462)
- 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)
- 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)
- Fixed the Collection example to use `gsd` instead of `eo:gsd`. [#399](https://github.com/Open-EO/openeo-api/issues/399)
- Clarify use of `user_id`. [#404](https://github.com/Open-EO/openeo-api/issues/404)
- Clarify that the relation type `version-history` should include `/.well-known/openeo` in the URL.
- 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)
- 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)
- Clarified ambiguous batch job status changes.
- Reflect that the `debug` process has been renamed to `inspect`.
- 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)
- Clarified schematically the applicability of JSON Schema extensions (`parameters`, `returns`, `dimensions`) and their relation to the subtypes
- `GET /`: Removed the superfluous default value for `currency`. [#423](https://github.com/Open-EO/openeo-api/issues/423)
- `GET /credentials/oidc`: Clarify that clients may add additional scopes
- `GET /me`: Clarify the behavior of the field `budget`.
- `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)
- `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.
- `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)
- Several appearances of `nullable` were clarified according to the lint report by Spectral
- Clarify how the well-known document works [#460](https://github.com/Open-EO/openeo-api/issues/460)
- Clarify handling of JSON Schema versions

## [1.1.0] - 2021-05-17

### Added
Expand Down Expand Up @@ -34,7 +96,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Clarified that job results require the property `datetime` and allow for additional properties. [#362](https://github.com/Open-EO/openeo-api/issues/362)
- Clarified that billing plans, service names and file formats must be accepted case-insensitive. [#371](https://github.com/Open-EO/openeo-api/issues/371)
- Clarified that the first provider listed at `GET /credentials/oidc` is the default provider for OpenID Connect.
- 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)
- 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)
- Fixed casing of potential endpoints `GET /collections/{collection_id}/items` and `GET /collections/{collection_id}/items/{feature_id}`.
- Clarified allowed characters in the `path` for uploaded user files.

Expand Down Expand Up @@ -83,9 +145,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Additional dimensions in `cube:dimensions` can only be of type `other`.
- The extents `interval` and `bbox` can have multiple entries.
- Allow all STAC versions that are compatible to STAC 0.9.0.
- Process graph nodes have an additional field `namespace` to distinguish pre-defined and user-defined processes. The default behavior has not changed. [#305](https://github.com/Open-EO/openeo-api/issues/305)
- 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)
- Added `format: commonmark` to all properties supporting CommonMark formatting.
- `errors.json`: The pre-defined 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)
- `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)
- Added `FolderOperationUnsupported`, `UnsupportedApiVersion`, `PermissionsInsufficient`, `ProcessGraphIdDoesntMatch` and `PredefinedProcessExists`.
- Added variable `reason` to error `FilePathInvalid` and `type` to `FileTypeInvalid` and`ServiceUnsupported`.
- Replaced the following error messages. The variables in the messages may have changed, too.
Expand Down Expand Up @@ -272,7 +334,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- `GET /jobs/{job_id}/estimate` can return the estimated required storage capacity. [#122](https://github.com/Open-EO/openeo-api/issues/122)
- `GET /jobs/{job_id}` has two new properties:
- `progress` indicates the batch job progress when running. [#82](https://github.com/Open-EO/openeo-api/issues/82)
- `error` states the error message when a job errored out.
- `error` states the error message when a job stopped due to an error.
`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)
- `GET /.well-known/openeo` allows clients to choose between versions. [#148](https://github.com/Open-EO/openeo-api/issues/148)
- `GET /` (Capabilities):
Expand Down Expand Up @@ -369,6 +431,7 @@ Initial version.


[Unreleased]: <https://github.com/Open-EO/openeo-api/compare/master...dev>
[1.2.0]: <https://github.com/Open-EO/openeo-api/compare/1.1.0...1.2.0>
[1.1.0]: <https://github.com/Open-EO/openeo-api/compare/1.0.1...1.1.0>
[1.0.1]: <https://github.com/Open-EO/openeo-api/compare/1.0.0...1.0.1>
[1.0.0]: <https://github.com/Open-EO/openeo-api/compare/0.4.2...1.0.0>
Expand Down
25 changes: 23 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,13 @@ openEO develops an open API to connect R, Python and JavaScript clients to big E

## Versions / Branches

The [master branch](https://github.com/Open-EO/openeo-api/tree/master) is the 'stable' version of the openEO API specification. It is currently version **1.1.0** of the specification. The [draft branch](https://github.com/Open-EO/openeo-api/tree/draft) is where active development takes place.
The [master branch](https://github.com/Open-EO/openeo-api/tree/master) is the 'stable' version of the openEO API specification. It is currently version **1.2.0** of the specification. The [draft branch](https://github.com/Open-EO/openeo-api/tree/draft) is where active development takes place.

| Version / Branch | Status | Description |
| --------------------------------------------------------- | ----------- | ----------- |
| [draft](https://api.openeo.org/draft) | planned | *Unstable* - Next version. |
| [**1.1.0**](https://api.openeo.org) | **current** | Clarifications, STAC updates, return value for child processes, more details for logs and jobs, default clients for OIDC. [Changelog](CHANGELOG.md#110---2021-06-15). |
| [**1.2.0**](https://api.openeo.org) | **current** | Clarifications, new extensions, vector data cubes, STAC (API) updates, more link relation types, improved batch job results and logs. [Changelog](CHANGELOG.md#120---2023-05-31). |
| [1.1.0](https://api.openeo.org/1.1.0) | legacy | Clarifications, STAC updates, return value for child processes, more details for logs and jobs, default clients for OIDC. [Changelog](CHANGELOG.md#110---2021-06-15). |
| [1.0.1](https://api.openeo.org/1.0.1) | legacy | Clarifications, bugfixes and CORS improvements. [Changelog](CHANGELOG.md#101---2020-12-07). |
| [1.0.0](https://api.openeo.org/1.0.0) | legacy | First stable version of openEO. [Changelog](CHANGELOG.md#100---2020-07-17). |
| [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). |
Expand All @@ -26,10 +27,30 @@ The [master branch](https://github.com/Open-EO/openeo-api/tree/master) is the 's

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.

## Extensions

| Name | Version | Stability | Description |
| ---------------------------------------------- | ------- | ------------ | ----------- |
| [Commercial Data](extensions/commercial-data/) | 0.1.0 | experimental | Provides an interface for discovering, ordering and using commercial data. |
| [Federation](extensions/federation/) | 0.1.0 | experimental | Covers federation aspects, i.e. where multiple back-ends are exposed as a single API. |

## Repository

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

* [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.
* [errors.json](errors.json) is a list of potential global error codes and messages, excluding specific exceptions separately available for each process.
* The [assets](assets/) folder contains some useful additional files such as examples or schemas. All of these are non-binding additions. The source of truth are the top-level specification files.
* The [extensions](extensions/) folder contains extensions to the openEO API.

# Development

The `draft` branch is the latest version and is the one to create Pull Requests against.

For development some tools can be used:

1. Install [node and npm](https://nodejs.org) - should run with any recent version
2. Run `npm install` in this folder to install the dependencies
3. Run the linter for the OpenAPI file with `npm test`. This will lint the files and check against some best-practices. It uses `spectral` in the background.
4. To show the files nicely formatted in a web browser, run `npm start`. It starts a server and opens the API specification rendered with ReDoc in a web browser.
5. To create a static HTML page (e.g. for hosting it on GitHub Pages), you can run `npm run build` and it will create a `redoc.html` in this folder.
Loading