From a9fbc3eb17374d91e5fa6130aa8a3cf6bb4c7d81 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 19 May 2023 11:37:43 +0200 Subject: [PATCH] Crosswalk with OGC API - Processes --- crosswalks/oap-echo-example.json | 69 +++++++++++ crosswalks/ogcapi-processes.md | 186 ++++++++++++++++++++++++++++ crosswalks/openeo-echo-example.json | 59 +++++++++ 3 files changed, 314 insertions(+) create mode 100644 crosswalks/oap-echo-example.json create mode 100644 crosswalks/ogcapi-processes.md create mode 100644 crosswalks/openeo-echo-example.json diff --git a/crosswalks/oap-echo-example.json b/crosswalks/oap-echo-example.json new file mode 100644 index 00000000..d12bef3d --- /dev/null +++ b/crosswalks/oap-echo-example.json @@ -0,0 +1,69 @@ +{ + "id": "EchoProcess", + "title": "Echo Process", + "description": "This process accepts and number of input and simple echoes each input as an output.", + "version": "1.0.0", + "jobControlOptions": [ + "async-execute", + "sync-execute" + ], + "outputTransmission": [ + "value", + "reference" + ], + "inputs": { + "stringInput": { + "title": "String Literal Input Example", + "description": "This is an example of a STRING literal input.", + "schema": { + "type": "string", + "enum": [ + "Value1", + "Value2", + "Value3" + ] + }, + "doubleInput": { + "title": "Bounded Double Literal Input Example", + "description": "This is an example of a DOUBLE literal input that is bounded between a value greater than 0 and 10. The default value is 5.", + "schema": { + "type": "number", + "format": "double", + "minimum": 0, + "maximum": 10, + "default": 5, + "exclusiveMinimum": true + } + } + } + }, + "outputs": { + "stringOutput": { + "schema": { + "type": "string", + "enum": [ + "Value1", + "Value2", + "Value3" + ] + } + }, + "doubleOutput": { + "schema": { + "type": "number", + "format": "double", + "minimum": 0, + "maximum": 10, + "default": 5, + "exclusiveMinimum": true + } + } + }, + "links": [ + { + "href": "https://processing.example.org/oapi-p/processes/EchoProcess/execution", + "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute", + "title": "Execute endpoint" + } + ] +} \ No newline at end of file diff --git a/crosswalks/ogcapi-processes.md b/crosswalks/ogcapi-processes.md new file mode 100644 index 00000000..c17c0b8c --- /dev/null +++ b/crosswalks/ogcapi-processes.md @@ -0,0 +1,186 @@ +# Crosswalk between openEO API and OGC API - Processes + +This document gives a brief overview over similarities and differences between +- **openEO API, v1.2.0** +- **OGC API - Processes - Part 1: Core, v1.0.0** + +In the following I use **OAP** as an abbreviation for **OGC API - Processes - Part 1**. + +## General + +OCG API - Processes defines just processing, while the openEO API has a much broader scope. +openEO covers many parts that other OGC API specifications define, some are aligned some are not. + +The openEO API covers the following "categories" of endpoints: +- [API discovery](#api-discovery) - partially covered by OGC API - Processes - Part 1 +- [Authentication](#authentication) - not defined by OGC +- [Data Discovery](#data-discovery) - covered by various other OGC APIs (Coverages, EDR, Features, Records, ...) +- [Process Discovery](#process-discovery) - covered by OGC API - Processes - Part 1 + - [Pre-defined processes](#pre-defined-processes) - covered by OGC API - Processes - Part 1 + - [User-defined processes](#user-defined-processes) - covered by OGC API - Processes - Part 2 and 3 +- [Data Processing](#data-processing) - covered by OGC API - Processes - Part 1 and 3 + - [Synchronous processing](#synchronous-processing) - covered by OGC API - Processes - Part 1 + - [Batch Job processing](#batch-job-processing) - covered by OGC API - Processes - Part 1 + - [On-demand processing](#on-demand-processing) - covered by other OGC APIs (Maps, Tiles, ...) +- [File Storage](#file-storage) - not covered by OGC APIs +- [Data Access and Visualization](#data-access-and-visualization) - covered by other OGC APIs (Coverages, Features, Maps, Tiles, ...) + +Both APIs use HTTP as the basis and encourage HTTPS. +HTTP 1.1 is required for OAP, while openEO doesn't specify a specific HTTP version. +The APIs follow REST principles and make use of HTTP content negotiation. +The APIs make broad use of "Web Linking" (compatible between OAP and openEO). +Both specifications recommend the implementation of CORS. + +The default encoding for requests and response bodies is JSON. OGC API recommends to also support +HTML as an response body encoding. openEO uses client software to render HTML output from JSON. + +Both specifications make broad use of OpenAPI 3.0 and JSON Schema for specification purposes. + +Many API endpoints in OAP and openEO support pagination through links with the relation types `next` +and `prev`. These endpoints have a `limit` parameter to enable pagination for a specific page size. +**Note:** Pagination is rarely used in openEO implementations and most clients don't support it consistently. + +## API discovery + +Discovering the API, connecting to it and reading the capabilities is always the first step clients +need to execute. + +### Well-known document + +- openEO: `GET /.well-known/openeo` +- OAP: n/a + +openEO clients usually connect to the well-known document first to discover different versions or +implementations of a server. Thus a client can choose a suitable API versions inclusing choosing +between production and development instances. Then the openEO client connects to the selected +instance's [landing page](#landing-page), which OGC API - Processes clients always directly connect +to. openEO clients can usually also directly connect to the landing page though. + +This folder structure with the document resides usually outside of the actual API implementations, +i.e. in the root of the host or domain. + +### Landing page + +- openEO: `GET /` (required) +- OAP: `GET /` (required) + +As the landing pages both are based on top of OGC API - Common, they are very similar. + +Some differences include: +- openEO requires the following additional fields: + - Defined in OAP, but not required: `title`, `description` + - Not defined in OAP: `api_version`, `backend_version`, `stac_version`, `id`, `endpoints`, (`type`) +- The relation type to link to the conformance classes is `conformance` in openEO (originating from + OGC API - Features / STAC API) and `http://www.opengis.net/def/rel/ogc/1.0/conformance` in OAP. + Two links with the same target but different relation types will be required. +- The existance of API endpoints in openEO is primarily checked through `endpoints`, which is + not present in OAP. OAP uses links, which openEO primarily uses for non-API-related links. + Nevertheless, links such as required in OAP can be added easily to an openEO implementation. + The following additionl links are relevant for OAP: + - One of the link relations `service-desc` or `service-doc` is required in OAP. They should link + to an API description (e.g. OpenAPI or rendered HTML version). + - A link with relation type `http://www.opengis.net/def/rel/ogc/1.0/processes` to `/processes` is + required for OAP, but not in openEO. + - A link with relation type `http://www.opengis.net/def/rel/ogc/1.0/job-list` to `/jobs` can be + added in OAP, but is not present in openEO. + +### Conformanc classes + +- openEO: `GET /conformance` (optional) +- OAP: `GET /conformance` (required) + +Both endpoints are 100% equivalent. +OAP requires a separate endpoint that lists conformance classes. +openEO additionally allows to list the conformance classes in the landing page (follows STAC API). +Conformance classes are only fully defined since openEO API v1.2.0. + +## Authentication + +- openEO: `GET /credentials/basic` and/or `GET /credentials/oidc` +- OAP: n/a + +OpenEO defines two authentication mechanisms: +- OpenID Connect (primary) +- HTTP Basic (secondary, primarily for development/testing purposes) + +OAP doesn't define any authentication machanisms, but both authentication mechanisms can also be +implemented for OAP. The main issue will be that OAP clients will likely not support them. + +The availability of the authentication mechanisms is detected through the `endpoints` in the +[landing page](#landing-page) in openEO, while in OAP you need to parse the OpenAPI document for it +(which implicitly requires a link to an OpenAPI 3.0 file with relation type `service-desc` in the +landing page). + +## Data Discovery + +Data Discovery is not covered by OAP, but it can be "plugged in" through various other OGC APIs +(e.g. Coverages, EDR, Features, Records, ...). Except for OGC API - Processes - Part 3, it is not +clear how the processes defined in OAP can access resources from the other APIs. The processes +probably need to implement data access individually through OGC API clients. As such, OAP could +also be made compliant with STAC API - Collection and STAC API - Features. STAC API - Collections +is required by openEO, STAC API - Features is optional in openEO, but would likely be required to +allow data access through OAP processes. + +## Process Discovery + +OAP does not mandate the use of any specific process description to specify the interface of a +process. It defines a "default" encoding in the conformance class "OGC Process Description" though. + + TBC, there seems to be a + [conflicting statement](https://github.com/opengeospatial/ogcapi-processes/issues/325) in OAP. + +The openEO API specifies a single encoding for process descriptions. +This means in principle that OAP can return openEO processes, but it has to be assumed that OAP +client will expect OGC Process Descriptions and won't be able to read openEO processes by default. + +### Pre-defined processes + +- openEO: `GET /processes` (required) +- OAP: `GET /processes`, `GET /processes/{processID}` (both required) + +In openEO `GET /processes` returns the full process metadata, while in OAP it only returns a summary. +The general structure of the response of `GET /processes` is the same (`processes` and `links`). +The OGC Process Description and the openEO process description are not compatible though. + +openEO doesn't define an endpoint yet to retrieve an indivdual process such as +`GET /processes/{processID}` in OAP. +There is a [proposal](https://github.com/Open-EO/openeo-api/pull/348) available to add such an endpoint. +openEO has the concept of namespace for processes though and thus defines the endpoint at +`GET /processes/{namespace}/{process}` which would conflict with OAP. + +Some notable differences in the process description: +- OAP defines `jobControlOptions`, which is + [undefined in openEO](https://github.com/Open-EO/openeo-api/issues/429) yet +- OAP defines `outputTransmission`, which is + [probably](https://github.com/opengeospatial/ogcapi-processes/issues/326) not available in openEO +- OAP allows multiple outputs, openEO only allows a single output + (potential workaround: wrap in an array or object) + +Below is a simple process encoded in the two variants discussed here: +- [OGC Process Description](oap-echo-example.json) +- [openEO Process](openeo-echo-example.json) + +### User-defined processes + + TBD, lower priority as it's not covered by OAP. + +## Data Processing + +### Synchronous processing + +### Batch Job processing + +### On-demand processing + + TBD, lower priority as it's not covered by OAP. + +## File Storage + +- openEO: `/files` (various methods), `/files/{path}` (various methods) +- OAP: n/a + +As it is neither available in OAP nor in any of the OGC APIs, we don't make any comparisons here. + +## Data Access and Visualization + + TBD, lower priority as it's not covered by OAP. diff --git a/crosswalks/openeo-echo-example.json b/crosswalks/openeo-echo-example.json new file mode 100644 index 00000000..465cfaa9 --- /dev/null +++ b/crosswalks/openeo-echo-example.json @@ -0,0 +1,59 @@ +{ + "id": "EchoProcess", + "summary": "Echo Process", + "description": "This process accepts and number of input and simple echoes each input as an output.", + "parameters": [ + { + "name": "stringInput", + "description": "This is an example of a STRING literal input.", + "schema": { + "type": "string", + "enum": [ + "Value1", + "Value2", + "Value3" + ] + } + }, + { + "name": "doubleInput", + "description": "This is an example of a DOUBLE literal input that is bounded between a value greater than 0 and 10. The default value is 5.", + "schema": { + "type": "number", + "minimum": 0, + "maximum": 10, + "exclusiveMinimum": true + }, + "optional": true, + "default": 5 + } + ], + "returns": { + "schema": { + "type": "array", + "items": [ + { + "type": "string", + "enum": [ + "Value1", + "Value2", + "Value3" + ] + }, + { + "type": "number", + "minimum": 0, + "maximum": 10, + "exclusiveMinimum": true + } + ] + } + }, + "links": [ + { + "href": "https://processing.example.org/openeo/processes/EchoProcess/execution", + "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute", + "title": "Execute endpoint" + } + ] +} \ No newline at end of file