Adds auth description to common bindings document (#227)

* Add description * Remove auth sections * Remove auth sections from catalog
International-Data-Spaces-Association · Feb 15, 2024 · d2798fe · d2798fe
1 parent e5b658a
commit d2798fe
Show file tree

Hide file tree

Showing 4 changed files with 63 additions and 37 deletions.
diff --git a/catalog/catalog.binding.https.md b/catalog/catalog.binding.https.md
@@ -5,7 +5,6 @@ This specification defines a RESTful API over HTTPS for the [Catalog Protocol](.
 * [1 Introduction](#1-introduction)
   * [1.1 Prerequisites](#11-prerequisites)
   * [1.2 Catalog Error](#12-catalog-error)
-  * [1.3 Authorization](#13-authorization)
 * [2 Path Bindings](#2-path-bindings)
   * [2.1 The `catalog/request` Endpoint (Provider-side)](#21-the-catalogrequest-endpoint--provider-side-)
   * [2.2 The `catalog/datasets/:id` Endpoint (Provider-side)](#22-the-catalogdatasetsid-endpoint--provider-side-)
@@ -27,10 +26,6 @@ This specification defines a RESTful API over HTTPS for the [Catalog Protocol](.
 
 In the event of a request error, the [Catalog Service](../model/terminology.md#catalog-service) must return an appropriate HTTP code and a [Catalog Error](./catalog.protocol.md#33-error---catalog-error) in the response body.
 
-### 1.3 Authorization
-
-A [Catalog Service](../model/terminology.md#catalog-service) may require authorization. If the [Catalog Service](../model/terminology.md#catalog-service) requires authorization, requests must include an HTTP `Authorization` header with a token. The semantics of such tokens are not part of this specification.
-
 ## 2 Path Bindings
 
 | Endpoint                                  | Method | Description                |

diff --git a/common/common.binding.https.md b/common/common.binding.https.md
@@ -10,4 +10,8 @@ Each implementation must provide the version metadata endpoint, which must use t
 
 The contents of the response is a JSON object defined in the [Dataspace Protocol](./common.protocol.md#1-exposure-of-dataspace-protocol-versions).
 
-Note that if multiple [Connectors](../model/terminology.md#connector--data-service-) are hosted under the same base URL, a path segment appended to the base well-known URL can be used, for example, `https://example.com/.well-known/dspace-version/connector1.`
+Note that if multiple [Connectors](../model/terminology.md#connector--data-service-) are hosted under the same base URL, a path segment appended to the base well-known URL can be used, for example, `https://example.com/.well-known/dspace-version/connector1.`
+
+## 2 Authorization
+
+All requests to HTTPS endpoints should use the `Authorization` header to include an authorization token. The semantics of such tokens are not part of these specifications. The `Authorization` HTTP header is optional if the [Connector](../model/terminology.md#connector--data-service-) does not require authorization.
diff --git a/negotiation/contract.negotiation.binding.https.md b/negotiation/contract.negotiation.binding.https.md
@@ -2,28 +2,60 @@
 
 This specification defines a RESTful API over HTTPS for the [Contract Negotiation Protocol](./contract.negotiation.protocol.md).
 
-- [1 Introduction](#1-introduction)
-  - [1.1 Prerequisites](#11-prerequisites)
-  - [1.2 Contract Negotiation Error](#12-contract-negotiation-error)
-    - [1.2.1 State Transition Errors](#121-state-transition-errors)
-    - [1.2.2 Object Not Found](#122-object-not-found)
-    - [1.2.3 Unauthorized Access](#123-unauthorized-access)
-  - [1.3 Authorization](#13-authorization)
-- [2 Provider Path Bindings](#2-provider-path-bindings)
-  - [2.1 The `negotiations` Endpoint _(Provider-side)_](#21-the-negotiations-endpoint-provider-side)
-  - [2.2 The `negotiations/request` Endpoint _(Provider-side)_](#22-the-negotiationsrequest-endpoint-provider-side)
-  - [2.3 The `negotiations/:providerPid/request` Endpoint _(Provider-side)_](#23-the-negotiationsproviderpidrequest-endpoint-provider-side)
-  - [2.4 The `negotiations/:providerPid/events` Endpoint _(Provider-side)_](#24-the-negotiationsproviderpidevents-endpoint-provider-side)
-  - [2.5 The `negotiations/:providerPid/agreement/verification` Endpoint  _(Provider-side)_](#25-the-negotiationsproviderpidagreementverification-endpoint--provider-side)
-  - [2.6 The `negotiations/:providerPid/termination` Endpoint _(Provider-side)_](#26-the-negotiationsproviderpidtermination-endpoint-provider-side)
-- [3 Consumer Callback Path Bindings](#3-consumer-callback-path-bindings)
-  - [3.1 Prerequisites](#31-prerequisites)
-  - [3.2 The `negotiations/offers` Endpoint _(Consumer-side)_](#32-the-negotiationsoffers-endpoint-consumer-side)
-  - [3.3 The `negotiations/:consumerPid/offers` Endpoint _(Consumer-side)_](#33-the-negotiationsconsumerpidoffers-endpoint-consumer-side)
-  - [3.4 The `negotiations/:consumerPid/agreement` Endpoint _(Consumer-side)_](#34-the-negotiationsconsumerpidagreement-endpoint-consumer-side)
-  - [3.5 The `negotiations/:consumerPid/events` Endpoint _(Consumer-side)_](#35-the-negotiationsconsumerpidevents-endpoint-consumer-side)
-  - [3.6 The `negotiations/:consumerPid/termination` Endpoint _(Consumer-side)_](#36-the-negotiationsconsumerpidtermination-endpoint-consumer-side)
-
+- [Contract Negotiation HTTPS Binding](#contract-negotiation-https-binding)
+  - [1 Introduction](#1-introduction)
+    - [1.1 Prerequisites](#11-prerequisites)
+    - [1.2 Contract Negotiation Error](#12-contract-negotiation-error)
+      - [1.2.1 State Transition Errors](#121-state-transition-errors)
+      - [1.2.2 Object Not Found](#122-object-not-found)
+      - [1.2.3 Unauthorized Access](#123-unauthorized-access)
+  - [2 Provider Path Bindings](#2-provider-path-bindings)
+    - [2.1 The `negotiations` Endpoint _(Provider-side)_](#21-the-negotiations-endpoint-provider-side)
+      - [2.1.1 GET](#211-get)
+        - [Request](#request)
+        - [Response](#response)
+    - [2.2 The `negotiations/request` Endpoint _(Provider-side)_](#22-the-negotiationsrequest-endpoint-provider-side)
+      - [2.2.1 POST](#221-post)
+        - [Request](#request-1)
+        - [Response](#response-1)
+    - [2.3 The `negotiations/:providerPid/request` Endpoint _(Provider-side)_](#23-the-negotiationsproviderpidrequest-endpoint-provider-side)
+      - [2.3.1 POST](#231-post)
+        - [Request](#request-2)
+        - [Response](#response-2)
+    - [2.4 The `negotiations/:providerPid/events` Endpoint _(Provider-side)_](#24-the-negotiationsproviderpidevents-endpoint-provider-side)
+      - [2.4.1 POST](#241-post)
+        - [Request](#request-3)
+        - [Response](#response-3)
+    - [2.5 The `negotiations/:providerPid/agreement/verification` Endpoint  _(Provider-side)_](#25-the-negotiationsproviderpidagreementverification-endpoint--provider-side)
+      - [2.5.1 POST](#251-post)
+        - [Request](#request-4)
+        - [Response](#response-4)
+    - [2.6 The `negotiations/:providerPid/termination` Endpoint _(Provider-side)_](#26-the-negotiationsproviderpidtermination-endpoint-provider-side)
+      - [2.6.1 POST](#261-post)
+        - [Request](#request-5)
+        - [Response](#response-5)
+  - [3 Consumer Callback Path Bindings](#3-consumer-callback-path-bindings)
+    - [3.1 Prerequisites](#31-prerequisites)
+    - [3.2 The `negotiations/offers` Endpoint _(Consumer-side)_](#32-the-negotiationsoffers-endpoint-consumer-side)
+      - [3.2.1 POST](#321-post)
+        - [Request](#request-6)
+        - [Response](#response-6)
+    - [3.3 The `negotiations/:consumerPid/offers` Endpoint _(Consumer-side)_](#33-the-negotiationsconsumerpidoffers-endpoint-consumer-side)
+      - [3.3.1 POST](#331-post)
+        - [Request](#request-7)
+        - [Response](#response-7)
+    - [3.4 The `negotiations/:consumerPid/agreement` Endpoint _(Consumer-side)_](#34-the-negotiationsconsumerpidagreement-endpoint-consumer-side)
+      - [3.4.1 POST](#341-post)
+        - [Request](#request-8)
+        - [Response](#response-8)
+    - [3.5 The `negotiations/:consumerPid/events` Endpoint _(Consumer-side)_](#35-the-negotiationsconsumerpidevents-endpoint-consumer-side)
+      - [3.5.1 POST](#351-post)
+        - [Request](#request-9)
+        - [Response](#response-9)
+    - [3.6 The `negotiations/:consumerPid/termination` Endpoint _(Consumer-side)_](#36-the-negotiationsconsumerpidtermination-endpoint-consumer-side)
+      - [3.6.1 POST](#361-post)
+        - [Request](#request-10)
+        - [Response](#response-10)
 
 ## 1 Introduction
 
@@ -335,8 +367,8 @@ Authorization: ...
     "@type": "odrl:Offer",
     "@id": "urn:uuid:6bcea82e-c509-443d-ba8c-8eef25984c07",
     "odrl:target": "urn:uuid:3dd1add8-4d2d-569e-d634-8394a8836a88",
-    "odrl:assigner": "urn:tsdshhs636378",
-    "odrl:assignee": "urn:jashd766",
+    "dspace:providerId": "urn:tsdshhs636378",
+    "dspace:consumerId": "urn:jashd766",
     ...
   },
   "dspace:callbackAddress": "https://......"
@@ -370,8 +402,8 @@ Authorization: ...
     "@type": "odrl:Agreement",
     "odrl:target": "urn:uuid:3dd1add4-4d2d-569e-d634-8394a8836d23",
     "dspace:timestamp": "2023-01-01T01:00:00Z",
-    "odrl:assigner": "urn:tsdshhs636378",
-    "odrl:assignee": "urn:jashd766",
+    "dspace:providerId": "urn:tsdshhs636378",
+    "dspace:consumerId": "urn:jashd766",
     ...
   },
   "dspace:callbackAddress": "https://......"

diff --git a/transfer/transfer.process.binding.https.md b/transfer/transfer.process.binding.https.md
@@ -8,7 +8,6 @@ This specification defines a RESTful API over HTTPS for the [Transfer Process Pr
     * [1.2.1 State Transition Errors](#121-state-transition-errors)
     * [1.2.2 Object Not Found](#122-object-not-found)
     * [1.2.3 Unauthorized Access](#123-unauthorized-access)
-  * [1.3 Authorization](#13-authorization)
 * [2 Provider Path Bindings](#2-provider-path-bindings)
   * [2.1 The `transfers` Endpoint _(Provider-side)_](#21-the-transfers-endpoint-provider-side)
   * [2.2 The `transfers/request` Endpoint _(Provider-side)_](#22-the-transfersrequest-endpoint-provider-side)
@@ -47,10 +46,6 @@ If the TP does not exist, the [Consumer](../model/terminology.md#consumer) or [P
 
 If the client is not authorized, the [Consumer](../model/terminology.md#consumer) or [Provider](../model/terminology.md#provider) must return an HTTP 404 (Not Found) response.
 
-### 1.3 Authorization
-
-All requests should use the `Authorization` header to include an authorization token. The semantics of such tokens are not part of this specification. The `Authorization` HTTP header is optional if the [Connector](../model/terminology.md#connector--data-service-) does not require authorization.
-
 ## 2 Provider Path Bindings
 
 | Endpoint                                                | Method | Description                |