Federation Extension

CHANGELOG.md

@@ -8,12 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- New experimental [Federation Extension](./extensions/federation/README.md)
 - `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)
 - `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 /me`: New Relation types `alternate` and `related` for user-specific external pages. [#404](https://github.com/Open-EO/openeo-api/issues/404)
-- `GET /credentials/oids`: 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 /credentials/oids`: 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)
 - 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)

extensions/federation/README.md

@@ -0,0 +1,207 @@
+# Federation Extension
+
+The openEO API is a specification for interoperable cloud-based processing of large Earth observation datasets.
+
+This is an extension for federation aspects, i.e. where multiple back-ends are exposed as a single API.
+
+- Version: **0.1.0**
+- Stability: **experimental**
+
+**Note:** This document only documents the additions to the specification.
+Extensions can not change or break existing behavior of the openEO API.
+
+## Backend details
+
+A new required field `federation` is added to `GET /` to enable federation.
+
+### OpenAPI fragment
+
+```yaml
+schema:
+  type: object
+  required:
+    - 'federation'
+  properties:
+    'federation':
+      description: >-
+        Lists all back-ends that are part of this federation with details.
+        They keys of the object are the unique identifiers for the back-ends that are returned in sub-sequent requests (see below).
+      type: object
+      minProperties: 2
+      additionalProperties:
+        type: object
+        required:
+          - url
+        properties:
+          url:
+            type: string
+            format: uri
+            description: >-
+              URL to the versioned API endpoint of the back-end,
+              so a URL that is available through well-known discovery on the back-end.
+            example: https://openeo.provider.org/api/v1/
+          title:
+            type: string
+            description: Name of the back-end.
+          description:
+            type: string
+            description: A description of the back-end and its specifics.
+          status:
+            type: string
+            enum:
+              - online
+              - offline
+            description: Current status of the back-ends.
+            default: online
+          last_status_check:
+            type: string
+            format: date-time
+            description: The time at which the status of the back-end was checked last.
+          last_successful_check:
+            type: string
+            format: date-time
+            description: >-
+              If the `status` is `offline`: The time at which the back-end was checked and available the last time.
+              Otherwise, this is equal to the property `last_status_check`.
+```
+
+### Example
+
+```json
+{
+  "api_version": "1.1.0",
+  "federation": {
+    "vito": {
+      "title": "VITO",
+      "url": "https://openeo.vito.be"
+    },
+    "eodc": {
+      "title": "EODC",
+      "url": "https://openeo.eodc.eu"
+    },
+    "wwu": {
+      "title": "WWU Münster",
+      "url": "https://openeo.wwu.de",
+      "status": "offline",
+      "description": "Experimental integration of the WWU HPC"
+    }
+  },
+  ...
+}
+```
+
+## Lists of resources
+
+Clients will assume that all lists of resources are the a combination of all back-ends listed in `GET /`.
+Federated APIs can expose if any of the back-ends is not available and thus is not part of the response.
+
+Applies to:
+
+- `GET /collections`
+- `GET /processes`
+- `GET /file_formats`
+- `GET /process_graphs`
+- `GET /jobs`
+- `GET /jobs/{job_id}`
+- `GET /jobs/{job_id}/logs`
+- `GET /jobs/{job_id}/results`
+- `GET /services`
+- `GET /services/{service_id}/logs`
+
+The following two endpoints are not extensible and as such the additional field can't be added:
+
+- `GET /udf_runtimes`
+- `GET /service_types`
+
+*This is due to the fact that these two endpoints return an object with a key-value-pair per UDF runtime / service type and adding a key-value-pair for federation purposes would be interpreted as a new UDF runtime or service type by clients.*
+
+### OpenAPI fragment
+
+```yaml
+schema:
+  type: object
+  properties:
+    'federation:missing':
+      description: >-
+        Lists all back-ends that were not considered in the response (e.g. because they were not accessible).
+        If not given or empty, all back-ends were considered for creating the response.
+        Back-ends that were listed as offline in the capabilities still need to be listed here.
+      type: array
+      items:
+        type: string
+        description: The ID of a back-end.
+```
+
+### Example
+
+```json
+{
+  "federation:missing": ["wwu"],
+  "collections": [...],
+  "links": [...]
+}
+```
+
+## Resources supported only by a subset of back-ends
+
+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.
+This can also be embeded deeply into a hierarchical structure, e.g. for process or file format parameters.
+
+```yaml
+schema:
+  type: object
+  properties:
+    'federation:backends':
+      description: >-
+        Lists all back-ends that support or host the resource.
+        If not given, all back-ends support the resource.
+      type: array
+      minItems: 1
+      items:
+        type: string
+        description: The ID of a back-end.
+```
+
+**Note:** In Collections this should generally be provided on the top-level of the object.
+If users should be able to filter on back-ends in `load_collection`, please provide `federation:backends` as an element in `openeo:property_filters`.
+Then, `federation:backends` as defined in the schema above should also be provided in the `summaries`.
+
+### Examples
+
+#### Process
+
+```json
+{
+  "process_id": "example",
+  "federation:backends": ["vito", "eodc"],
+  "parameters": [
+    {
+      "name": "parameter1",
+      "description": "A parameter supported by both back-ends...",
+      "schema": {}
+    },
+    {
+      "name": "proprietary_parameter",
+      "description": "A parameter supported only by EODC.",
+      "federation:backends": ["eodc"],
+      "schema": {}
+    }
+  ]
+  ...
+}
+```
+
+#### Collection
+
+```json
+{
+  "stac_version": "1.0.0",
+  "id": "example",
+  "description": "...",
+  "summaries": {
+    "federation:backends": ["vito", "eodc"],
+    ...
+  },
+  ...
+}
+```