Releases: Open-EO/openeo-api
Releases · Open-EO/openeo-api
openEO API v1.3.0
Documentation: https://api.openeo.org/1.3.0/
Added
- New extensions:
GET /: New relation typeweb-editor#577GET /credentials/oidc: Addedauthorization_parametersproperty to enforce specific parameters for the authorization endpoint #534POST /result: Added response header "OpenEO-Identifier" to expose an identifier associated with a synchronous processing request.- Added
stacktraceto log entries (e.g. forGET /jobs/{job_id}/logs) #512 - Added
versionproperty toGET /processes#517 - Added
queued,startedandunpublishedto the batch job metadata and the corresponding STAC results #542 - Added a status diagram that explains the status changes of batch jobs #436
- Added all the batch job timestamps (including the new timestamps above) to the Collection type of batch job results
- Support for standard JSON Web Tokens (JWT) being used as Bearer tokens #558
Deprecated
- Deprecated the openEO-specific Bearer token format (authentication mechanism/provider id/access token) #558
- STAC 0.9.x
Changed
- Updated Federation Extension to v0.2.0
- Migrate from openEO-specific tokens to JWT, i.e. deprecating the openEO-specific format in favor of JWT #558
GET /: Requires the fieldstypeandconformsToGET /udf_runtimes: Requires at least one UDF runtime to be provided. #511
Fixed
GET /conformance: Added missing security definitionsGET /file_formats: Base parameter on top of normal JSON Schema, not Process JSON SchemaPATCH /services/{service_id}andPATCH /jobs/{job_id}: Explicitly allow updating back-end specific properties (as inPOST)GET /services/{service_id}andGET /jobs/{job_id}: Explicitly allow listing back-end specific properties (as provided inPOST)GET /jobs/{job_id}/results: Clarify that signed URLs (used as "canonical" link) should be regenerated each time.GET /jobs/{job_id}/results: Clarify that "canonical" job result link should include/encode the original query parameters- Clarified for log levels which default values apply
- Clarified how the relation types
license,version-historyandauthorcan be used to enrich the process metadata. #531 - Clarified the behaviour of
federation:backendsforPOST /validation - Clarified the meaning of
expiresin batch job results - Clarified that
last_successful_check(from Federation Extension) can be null. - Clarified the relation between result and end nodes, the usage of the result flag, and the relation between the outermost ("root") and child process graphs #547
- Fixed various OpenAPI issues reported by redocly lint
openEO API v1.2.0
Documentation: https://api.openeo.org/1.2.0/
[1.2.0] - 2021-05-25
Added
- New extensions:
GET /: New Relation types: #404create-formto link to the registration pagerecovery-formto link to the credentials recovery page.
GET /file_formats: Addpointcloudto thegis_data_types. #475GET /me: New Relation typesalternateandrelatedfor user-specific external pages. #404GET /credentials/oidc: Allowauthorization_codeandurn:ietf:params:oauth:grant-type:device_code(both without PKCE) as grants fordefault_clients. #410GET /jobsandGET /jobs/{job_id}: Added a links property that can for example link to results and logs. #453GET /jobs/{job_id}/results:- Recommendation to add a link with relation type
canonicalwhich points to a signed URL with the same content as the response. #397 - Added metadata field
openeo:statusto indicate the job status (and whether the result is complete or not). - Added parameter
partialto allow retrieving incomplete results, which must also add the new propertyopeneo:statusto the metadata. #430
- Recommendation to add a link with relation type
GET /jobs/{job_id}/logs,GET /services/{service_id}/logs: Addedlevelparameter to requests to set the minimum log level returned by the response. #485- Added property
log_levelto secondary web service, batch job and synchronous processing endpoints to indicate the minimum severity level that should be stored for logs. #329 GET /jobs/{job_id}/logs,GET /services/{service_id}/logsandPOST /result: Addedlevelproperty in responses to reflect the minimum log level that may appear in the response. #329- Recommendation to add media types and titles to links for a better user experience.
- Allow the relation type
canonicalto be used generally for (shared) resources (e.g. UDPs or batch jobs) without requiring Bearer authentication. #405 - Recommendation for UDF runtime names. #409
- Processes: Added
dimensionsschema for subtypedatacube - Collections: Added
geometrydimension type tocube:dimensions - New endpoint for metadata filters (queryables):
/collections/{collection_id}/queryables. Also adds a new rel type to the collection links. #396
Changed
- Updated STAC specification examples and references to v1.0.0, please see the STAC changelog for all changes between 0.9 and 1.0.
cube:dimensions:reference_systemis 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
- Minimum value for
costsandbudgetis 0. GET /jobs/{job_id}/estimate: If a batch job can't be estimated reliably, aEstimateComplexityerror should be returned. #443- The
/conformanceendpoint is now generally used for OGC APIs, STAC API and openEO.conformsTois also exposed inGET /for STAC APIs. The openEO API and all extensions got individual conformance classes. #186
Fixed
- Explicitly mention the use of HTTP content negotiation
- Clarify that the default charset is UTF-8 #462
- Fixed inconsistencies in errors.json: removed
ProcessGraphIdDoesntMatch, clarifiedProcessGraphMissing, addedProcessInvalidandProcessGraphInvalid. #394, #395, #401 - Fixed the default value for the version number in the API url (
v1.0->v1) and improved the description for API versioning. #393 - Fixed the Collection example to use
gsdinstead ofeo:gsd. #399 - Clarify use of
user_id. #404 - Clarify that the relation type
version-historyshould include/.well-known/openeoin the URL. - Clarify that clients should (re-)request capabilities and discovery endpoints with token if available and supported. #416
- Clarify the fields
plan(for processing requests) andbilling_plan(inGET /andGET /me). #425 #426 - Clarified ambiguous batch job status changes.
- Reflect that the
debugprocess has been renamed toinspect. - Clarified uniqueness constraints for identifiers. #449 #454
- Clarified schematically the applicability of JSON Schema extensions (
parameters,returns,dimensions) and their relation to the subtypes GET /: Removed the superfluous default value forcurrency. #423GET /credentials/oidc: Clarify that clients may add additional scopesGET /me: Clarify the behavior of the fieldbudget.GET /jobs/{job_id}/logs,GET /services/{service_id}/logsandPOST /result: Clarified the formatting of themessageproperty. #455GET /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 /servicesandGET /services/{service_id}: Clarify thatenabledis required by removing the default value. #473- Several appearances of
nullablewere clarified according to the lint report by Spectral - Clarify how the well-known document works #460
- Clarify handling of JSON Schema versions
openEO API v1.1.0
Documentation: https://api.openeo.org/1.1.0/
[1.1.0] - 2021-05-17
Added
GET /processesandGET/PUTfor/process_graphs/{process_graph_id}: Allow specifying the return values processes receive from child processes. #350- Recommendation that
POST /resultreturns atarfile if the result consists of multiple files. #349 GET /credentials/oidccan provide a set of default client ids for OpenID Connect. #366experimentalanddeprecatedflags added for file formats, service types, udf runtimes, udf runtime versions, udf runtime libraries and all related parameters and schemas. #354GET /jobs/{job_id}andGET /services/{service_id}:usageproperty added for usage metrics. #370GET /jobs/{job_id}/logsandGET /services/{service_id}/logs:- Added error
ResultLinkExpired. #379 GET /me: A default plan per user can be specified. #375
Changed
- API doesn't discourage usage of
multipleOfin JSON Schemas any longer. GET /jobs/{job_id}/resultssupports to return a STAC Collection. #343- Updated STAC schemas to better support versions 1.x.x.
- The first extent in a Collection is always the overall extent, followed by more specific extents. #369
Fixed
- Clarified how process exceptions should be used. #352
- Clarified that job results schould be stored as valid STAC catalogs. #363
- Clarified that job results require the property
datetimeand allow for additional properties. #362 - Clarified that billing plans, service names and file formats must be accepted case-insensitive. #371
- Clarified that the first provider listed at
GET /credentials/oidcis the default provider for OpenID Connect. - Clarified that
GET /jobs/{job_id}/resultsshould always return valid signed URLs and the endpoint can be used to renew the signed URLs. #379 - Fixed casing of potential endpoints
GET /collections/{collection_id}/itemsandGET /collections/{collection_id}/items/{feature_id}. - Clarified allowed characters in the
pathfor uploaded user files.
openEO API v1.0.1
Clarifications, bugfixes and CORS improvements.
Documentation: https://api.openeo.org/1.0.1/
1.0.1 - 2020-12-07
Changed
GET /collectionsandGET /collections/{collection_id}: Units for STAC dimensions incube:dimensionsshould be compliant to UDUNITS-2 units (singular) whenever available.GET /file_formats: It is recommended to at least specify one of the data types ingis_data_types. #325
Fixed
- Cross-Origin Resource Sharing (CORS):
GET /: Missing optionOPTIONSadded to allowedmethodsfor theendpoints. #324- For
PATCHrequests: Clarified that no default values apply (forbudget,enabledandplan). Data is only changed on the back-end if new data is explicitly specified by the client. - For
POSTrequests with aplanproperty: Clarify that the default value isnull. GET /jobs/{job_id}/results: Clarified the use of thetypeFeaturein the GeoJSON result response. #327- Add missing
{namespace}placeholder toProcessUnsupportederror message. #328 - Fixed JSON Schema links to point to draft-07 instead of draft/2019-09.
GET /jobs/{job_id}/estimate: Enforce in the response schema that "at least one ofcosts,durationorsizeMUST be provided."
openEO API v1.0.0
First stable release!
Documentation: https://api.openeo.org/1.0.0/
1.0.0 - 2020-07-17
Added
GET /me: Added optionalnameproperty to better separate an internal user id from a displayable user name. Adopted description ofuser_idaccordingly.GET /udf_runtimes:- Added optional
titleproperty for UDF runtimes. #266 - Added required
typeproperty for UDF runtimes to support better code generation.
- Added optional
GET /service_types: Added optionaltitleanddescriptionproperties for service types. #266GET /file_formats: Added optionaldescriptionproperty for file formats. #266GET /collections/{collection_id}andGET /processes: Mention of linkreltypeexampleto refer to examples. #285GET /collections/{collection_id}: Added optionalassetsproperty for collection-level assets. This may link to visualizations for example. #211GET /collections,GET /jobs,GET /process_graphs,GET /services: Allow all non-scalar properties to be part of the response although strongly discouraged.
Changed
GET /credentials/oidc: fieldscopesis not required anymore, but when specified, it should contain theopenidscope. #288GET /.well-known/openeoandGET /:productionfields default tofalseinstead oftrue.GET /jobs/{job_id}/logsandGET /services/{service_id}/logs:pathproperty is not required any longer. #320GET /file_formats:parametersis now required for each file format. #318GET /service_types:configurationandprocess_parametersare now required for each service. #318GET /service_typesandGET /file_formats:- Allow full JSON Schema for parameters, instead of a very limited subset.
- Instead of the proprietary property
exampleuseexamplesfrom JSON Schema instead.
GET /collectionsandGET /collections/{collection_id}:- Additional dimensions in
cube:dimensionscan only be of typeother. - The extents
intervalandbboxcan have multiple entries.
- Additional dimensions in
- Allow all STAC versions that are compatible to STAC 0.9.0.
- Process graph nodes have an additional field
namespaceto distinguish pre-defined and user-defined processes. The default behavior has not changed. #305 - Added
format: commonmarkto all properties supporting CommonMark formatting. errors.json: The pre-defined error messages have been reworked. #272, #273- Added
FolderOperationUnsupported,UnsupportedApiVersion,PermissionsInsufficient,ProcessGraphIdDoesntMatchandPredefinedProcessExists. - Added variable
reasonto errorFilePathInvalidandtypetoFileTypeInvalidandServiceUnsupported. - Replaced the following error messages. The variables in the messages may have changed, too.
ProcessArgumentUnsupported->ProcessParameterUnsupportedProcessArgumentInvalid->ProcessParameterInvalidProcessParameterMissingandProcessArgumentRequired->ProcessParameterRequiredServiceArgumentUnsupported->ServiceConfigUnsupportedServiceArgumentInvalid->ServiceConfigInvalidServiceArgumentRequired->ServiceConfigRequired
- 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 asexceptions.
- Added
Removed
GET /processes: Examples containing process graphs. Use links withreltypeexampleandtypeset toapplication/jsoninstead. #285subtype-schemas.json. It's now published as part of openeo-processes.
Fixed
/.well-known/openeo:GET /jobs/{job_id}/results: Clarified that unlocated results setgeometrytonulland omit thebboxproperty.GET /jobs/{job_id}/logs: Clarified that back-ends can log at any stage of the job. #315POST /jobsandPOST /services: Clarified definition ofLocationheader inHTTP 201responses. #269GET /service/{service_id}: Propertyconfigurationis required instead of a non-existing property namedparameters.POST /validation: Clarify that unresolvable process parameters must not throw. #314- Formally forbid 5 elements in bounding boxes.
- Re-use corresponding schema for header
OpenEO-Identifier(addspattern). - Parameters passed to child process graphs are not defined recursively any longer. #268
- Parameters for child process graphs are not specified for return values and service type parameters any longer. #268
- Clarified the expected behavior for process parameters, if a default value is given and the parameter is implicitly set to be required. #303
- Several clarifications and improvements for the documentation.
openEO API v1.0.0 RC2
1.0.0-rc.2 - 2020-02-20
Added
PUT /process_graphs/{process_graph_id}to store and replace custom process-graphs. #260/jobs/{job_id}/logsandGET /services/{service_id}/logs: Reintroduced the missingoffsetparameter.
Changed
- For batch jobs (
/jobs), services (/services) and sync. processing (/result) the propertyprocess_graphgot replaced byprocess. It contains a process graph and optionally all process metadata. #260 GET /process_graphs: Fieldidis required for each process.- Several properties in user-defined processes can now be
null(see also #264):GET /process_graphsandGET /process_graphs/{process_graph_id}: Process propertiessummary,description,parametersandreturns.POST /validation: Process propertyid.- Child processes in process graphs (fka callbacks):
id,summary,description,parametersandreturns.
Removed
POST /process_graphsandPATCH /process_graphs/{process_graph_id}. UsePUT /process_graphs/{process_graph_id}instead. #260
Fixed
- Added
$idto JSON Schema file for subtypes. - Fixed invalid EPSG code example.
- Fixed collection example (
sat:cloud_coverchanged toeo:cloud_cover). - Fixed invalid JSON Schema for process graph validation (used
from_argumentinstead offrom_parameter). - Clarified how version numbers in well-known discovery are compared. #259
- Clarified that back-ends not supporting pagination will return all resources.
- Clarified how
from_parameteris resolved in case no value is given. - Clarified
GET .../logsendpoint behaviour. - Removed outdated error codes from
errors.json.
openEO API v1.0.0 RC1
1.0.0-rc.1 - 2020-01-31
Note: The user and developer documentation has been moved to openeo.org.
Added
GET /:GET /collectionsandGET /collections/{collectionId}:GET /conformancehas been added for OCG API compliance. Back-ends may implement it for compatibility with OGC API clients.POST /result: May add a link to a log file in the header. #214GET /jobs/{job_id}/logsandGET /services/{service_id}/logs: Endpoints that publish logging information. #214GET /files,GET /jobs,GET /process_graphs,GET /services,GET /collections,GET /processes: Addedlimitparameter for pagination and clarified how to use links for pagination. #103- JSON Schema for the defined schema
subtypes.
Changed
- The concept of callbacks has simply been renamed to process graph. Schema format/subtype
callbackhas been renamed toprocess-graph. #216 - Unsupported endpoints are not forced to return a
FeatureUnsupported(501) error and can return a simpleNotFound(404) instead. - If
currencyreturned byGET /isnull,costsandbudgetare unsupported.costsandbudgetfields in various endpoints can be set tonull(default). - Official support for CommonMark 0.29 instead of CommonMark 0.28. #203
- The parameter
user_idhas been removed from the endpoints to manage user files (/files/{user_id}). #218 - Schema subtype
band-nameallows common band names, too. Processes#77 - Link property
relis required. - OpenAPI string format
urlhas been replaced withuri. - Process graphs:
from_argumenthas been renamed tofrom_parameter.callbackhas been renamed toprocess_graph.from_parametercan access parameters defined in parent scopes.from_parametercan be used in the top-level process graph.- Process graph variables (objects with
variable_idetc.) have been removed.
GET /jobs,GET /jobs/{job_id},GET /servicesandGET /services/{service_id}: Renamed fieldsubmittedtocreatedfor consistency with STAC job results. Also renamed the corresponding value in the fieldstatusfor batch jobs.GET /: Propertylinksis required.GET /service_types:variableshas been renamed toprocess_parametersand has a different schema now. #161GET /service_types,POST /services,GET /services/{service_id},PATCH /services/{service_id}:parameterhas been renamed toconfigurationto not overlap withprocess_parameters.GET /processes:- Default values are now specified on the parameter-level, not in the JSON schemas.
- Multiple data types in parameters or return values are supported as arrays. Using
anyOfis discouraged. - Parameters are defined as array.
parameter_orderis therefore removed and the name is part of the parameter object. #239 - Process graph (callback) parameters have a new, more advanced schema, allowing to define more aspects of the process graph parameters. #239
- Return values don't require a description any longer.
requiredwas replaced withoptionalwith inverted behavior.
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 asGET /processes. Each process graph is now basically a process a user can use in other process graphs.GET /collectionsandGET /collections/{collectionId}: Updated STAC to version 0.9.0. See the STAC Changelog for more details. #247, #204.GET /credentials/oidc: Changed response to support multiple OpenID Connect identity providers (#201) and clarified workflow overall.- Bearer token are built from the authentication method, an optional provider id and the token itself. #219
GET /udf_runtimes:descriptionfields don't allownullvalues any longer.GET /output_formatsrenamed toGET /file_formatsto allow listing input file formats. #215- The structure of the response has changed. The former response body for the output formats is now available in the property
output. - The input file formats are now available in the property
inputwith the same schema as for output formats. - Additionally, each format can have a
title.
- The structure of the response has changed. The former response body for the output formats is now available in the property
GET /jobs/{job_id}/results:- Response body for status code 200 has changed to be a valid STAC Item, allows content type
application/geo+json. - Response body for status code 424 has been extended.
- Response body for status code 200 has changed to be a valid STAC Item, allows content type
Deprecated
- The processes should not use the JSON Schema keyword
formatany longer. Instead use the custom keywordsubtype. #233 - PROJ definitions are deprecated in favor of EPSG codes and WKT2. #58
Removed
- Process graph variables. Use Parameter References instead.
GET /processes:media_typeremoved from parameters and return values. UsecontentMediaTypein the JSON Schema instead.GET /job/{job_id}: Removed propertyerror. Request information fromGET /job/{job_id}/logsinstead.GET /job/{job_id}/results:- Metalink XML encoding has been removed. #205
Expiresheader has been removed, useexpiresproperty in the response body instead.
GET /credentials/basicdoesn't return auser_id. Instead request it fromGET /me.GET /collections/{collectionId}: Removed optional STAC extensions from the API specification. Inform yourself about useful STAC extensions instead. #176GET /service_typesdoesn't supportattributesany longer.
Fixed
- Service parameters and attributes in
GET /service_typesand output format parameters inGET /file_formats(previouslyGET /output_formats) now have atype, which was previously only mentioned in examples. GET /processes: Parametersargumentsandprocess_graphcan't be used together in process examples.GET ./well-known/openeo: Clarified how clients and back-ends should implement well-known discovery. #202
openEO API v0.4.2
Changed
- Updated the process catalog, see the separate changelog.
Added
- Basic JSON Schema for process graph validation.
Removed
- Disallowed CommonMark in descriptions of process graph variables and process graph nodes.
Fixed
- Improved documentation with several clarifications, better examples and more.
- SAR Bands had a required but undefined property. #187
- Clarified how file paths in the URL must be encoded for file handling.
- OpenAPI
nullableissues:- Removed
nullfrom SAR Bandsenumfor OpenAPI code generator, is handled bynullable. OpenAPI-Specification#1900 nullabledoesn't combine well withanyOf,allOfandoneOf, therefore placednullablealso in one of the sub-schemas. OpenAPI-Specification#1368
- Removed
openEO API v0.4.1
Changed
- Updated the process catalog, see the separate changelog.
Removed
- The property
sar:absolute_orbitinGET /collections/{collection_id}has been removed. - Sending a Bearer token to
GET /credentials/oidcis not allowed any longer.
Fixed
- Improved and clarified the documentation and descriptions.
GET /collections/{collection_id}:propertiesinGET /collections/{collection_id}doesn't require any of the integrated STAC extensions any longer.- The property
sci:publicationsinGET /collections/{collection_id}was ported over incorrectly from STAC. The data type has been changed from object to array.
GET /jobs/{job_id}/resultswas expected to return HTTP status code 424 with an error message, but it was specified in/jobs/{job_id}/estimateinstead. The definition was moved. #177pathinGETandPUT/files/{user_id}is required again.- Fixed several issues in the client development guidelines.
openEO API v0.4.0
Added
GET /jobs/{job_id}/estimatecan return the estimated required storage capacity. #122GET /jobs/{job_id}has two new properties:GET /.well-known/openeoallows clients to choose between versions. #148GET /(Capabilities):GET /processes(Process discovery):- Processes can be categorizes with the
categoryproperty. - Parameters can be ordered with the
parameter_orderproperty instead of having a random order. - Support for references to other processes in descriptions.
- Processes and parameters can be declared to be
experimental.
- Processes can be categorizes with the
GET /output_formatsandGET /service_typescan now provide links per entry.GET /udf_runtimesprovide a list of UDF runtime environments. #87GET /service_typesallows to specifyvariablesthat can be used in process graphs. #172
Changed
- Completely new version of the processes.
- Changed process graph to a flexible graph-like structure, which also allows callbacks. #160
- Updated
GET /collectionsandGET /collections/{collection_id}to follow STAC v0.6.2. #158, #173 - The
process_graph_idof stored process graphs, theservice_idof services and thejob_idof jobs has changed toidin responses. #130 - The
statusproperty for jobs is now required. POST /previewrenamed toPOST /result. #162GET /(Capabilities):/files/{user_id}/{path}File management:GET /processes(Process discovery):POST /validation(Process graph validation):- Behavior for
DELETE /jobs/{job_id}/resultsandPOST /jobs/{job_id}/resultsspecified depending on the job status. Clarified status changes in general. #142 - Improved client development guidelines. #124, #138
Removed
- Numeric openEO error codes. Replaced in responses with textual error codes. #139
- Query parameters to replace process graph variables in
GET /process_graphs/{process_graph_id}. #147 min_parametersanddependenciesfor parameters in process descriptions returned byGET /processes.- Replaced output format properties in favor of an export process, which has resulted in in the removal of:
Fixed
- Added missing
Access-Control-Expose-Headersheader to required CORS headers. - Some endpoints didn't include authentication information.
GET /jobs/{job_id}/estimate: Propertydownloads_includedhad a wrong default value.