From d8e58f5935954fe5370c272d980c2f887347b031 Mon Sep 17 00:00:00 2001
From: Matthias Mohr <m.mohr@uni-muenster.de>
Date: Fri, 4 Jun 2021 16:35:31 +0200
Subject: [PATCH] `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

---
 CHANGELOG.md |  4 ++++
 openapi.yaml | 27 ++++++++++++++++++++++++---
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9ec34eef..d99aaff8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased / Draft
 
+### Added
+
+- `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)
+
 ### Changed
 
 - Updated STAC specification examples and references to v1.0.0.
diff --git a/openapi.yaml b/openapi.yaml
index a8dfd56b..0fc339a8 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -3048,6 +3048,11 @@ paths:
         but regenerated with new expiration time.
         Signed URLs that expired MAY return the openEO error `ResultLinkExpired`.
 
+        It is **strongly recommended** to add a link with relation type `canonical`
+        to the STAC Item or STAC Collection, which points to this STAC document
+        using a signed URL. This way the STAC metadata can be used by non-openEO
+        clients without additional authentication steps.
+
         If processing has not finished yet requests to this endpoint MUST be
         rejected with openEO error `JobNotFinished`.
       tags:
@@ -3139,11 +3144,14 @@ paths:
                           roles:
                             - metadata
                       links:
-                        - rel: item
+                        - rel: canonical
                           type: application/json
+                          href: https://example.openeo.org/api/download/583fba8b2ce583fba8b2ce/collection.json
+                        - rel: item
+                          type: application/geo+json
                           href: https://example.openeo.org/api/download/583fba8b2ce583fba8b2ce/item_1.json
                         - rel: item
-                          type: application/json
+                          type: application/geo+json
                           href: https://example.openeo.org/api/download/583fba8b2ce583fba8b2ce/item_2.json
             application/geo+json:
               schema:
@@ -3783,7 +3791,7 @@ components:
           $ref: '#/components/schemas/stac_assets'
         links:
           type: array
-          description: >-
+          description: |-
             Links related to this batch job result, e.g. a link to an 
             invoice, additional log files or external documentation.
 
@@ -3792,10 +3800,19 @@ components:
             Clients MUST NOT download the data referenced in the links by
             default.
 
+            It is **strongly recommended** to add a link with relation type
+            `canonical`, which points to this STAC document using a signed URL.
+             This way the STAC metadata can be used by non-openEO clients
+             without additional authentication steps.
+
             For relation types see the lists of
             [common relation types in openEO](#section/API-Principles/Web-Linking).
           items:
             $ref: '#/components/schemas/link'
+          example:
+            - rel: canonical
+              type: application/geo+json
+              href: https://example.openeo.org/api/download/583fba8b2ce583fba8b2ce/item.json
     file_format:
       x-additionalPropertiesName: File Format Name
       title: File Format
@@ -4233,6 +4250,10 @@ components:
             catalog service such as OGC CSW, a human-readable HTML version or a
             metadata document following another standard such as ISO 19115 or DCAT.
 
+            6. `canonical` (primarily for batch job results): A signed URL
+            which points to this STAC document. This way the STAC metadata can
+            be used by non-openEO clients without additional authentication steps.
+
             For additional relation types see also the lists of
             [common relation types in openEO](#section/API-Principles/Web-Linking)
             and the STAC specification for Collections.