From aff274d6a35405d351b4388cb5baaaf6834e5984 Mon Sep 17 00:00:00 2001
From: Julia Pampus <72392527+juliapampus@users.noreply.github.com>
Date: Thu, 7 Sep 2023 10:10:12 +0200
Subject: [PATCH] chore: add http endpoint for provider initiated CN (#141)

* Added 3.2 The consumer negotiations/offers resource

* Update contract.negotiation.binding.https.md

* Update contract.negotiation.binding.https.md

* fix: apply feedback

---------

Co-authored-by: Konfr <121265758+Konfr@users.noreply.github.com>
---
 .../contract.negotiation.binding.https.md     | 61 ++++++++++++++++---
 negotiation/contract.negotiation.protocol.md  |  3 +
 2 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/negotiation/contract.negotiation.binding.https.md b/negotiation/contract.negotiation.binding.https.md
index 0a6b3800..e1cb8c93 100644
--- a/negotiation/contract.negotiation.binding.https.md
+++ b/negotiation/contract.negotiation.binding.https.md
@@ -187,10 +187,57 @@ All callback paths are relative to the `callbackAddress` base URL specified in t
 the `callbackAddress` is specified as `https://connector.consumer/callback` and a callback path binding is `negotiations/:id/offers`, the resolved URL will
 be `https://connector.consumer.com/callback/negotiations/:id/offers`.
 
-### 3.2 The consumer `negotiations/:id/offers` resource
+### 3.2 The consumer `negotiations/offers` resource
 
 #### 3.2.1 POST
 
+A contract offer is started and placed in the `OFFERED` state when a provider POSTs a
+[ContractOfferMessage](./message/contract-offer-message.json) to `negotiations/offers`:
+
+```
+POST https://connector.provider.com/negotiations/offers
+
+Authorization: ...
+
+{
+  "@context": "https://w3id.org/dspace/v0.8/context.json",
+  "@type": "dspace:ContractOfferMessage"
+  "@id": "urn:uuid:dcbf434c-eacf-4582-9a02-f8dd50120fd3",
+  "dspace:dataset": "urn:uuid:3dd1add8-4d2d-569e-d634-8394a8836a88",
+  "dspace:offer": {
+    "@type": "odrl:Offer",
+    "@id": "...",
+    "target": "urn:uuid:3dd1add8-4d2d-569e-d634-8394a8836a88"
+  }
+  "dspace:callbackAddress": "https://..."
+}
+```
+
+The callbackAddress property specifies the base endpoint URL where the client receives messages associated with the contract negotiation. Support for the HTTPS scheme is required. Implementations may optionally support other URL schemes.
+
+Callback messages will be sent to paths under the base URL as described by this specification. Note that consumer connectors should properly handle the cases where a trailing / is included with or absent from the callbackAddress when resolving full URL.
+
+The @id is the correlation id that will be used for callback messages.
+
+The consumer connector must return an HTTP 201 (Created) response with the location header set to the location of the contract negotiation and a body containing the ContractNegotiation message:
+
+```
+Location: /negotiations/urn:uuid:dcbf434c-eacf-4582-9a02-f8dd50120fd3
+
+{
+  "@context": "https://w3id.org/dspace/v0.8/context.json",
+  "@type": "dspace:ContractNegotiation"
+  "@id": "urn:uuid:dcbf434c-eacf-4582-9a02-f8dd50120fd3",
+  "dspace:state" :"OFFERED"
+}
+```
+
+Note that if the location header is not an absolute URL, it must resolve to an address that is relative to the base address of the Offer.
+
+### 3.3 The consumer `negotiations/:id/offers` resource
+
+#### 3.3.1 POST
+
 A provider may make an offer by POSTing a [ContractOfferMessage](./message/contract-offer-message.json) to the `negotiations/:id/offers` callback:
 
 ```
@@ -213,9 +260,9 @@ Authorization: ...
 If the message is successfully processed, the consumer provider connector must return an HTTP 200 (OK) response. The response body is not specified and clients are not required to
 process it.
 
-### 3.3 The consumer `negotiations/:id/agreement` resource
+### 3.4 The consumer `negotiations/:id/agreement` resource
 
-#### 3.3.1 POST
+#### 3.4.1 POST
 
 The provider connector can POST a [ContractAgreementMessage](./message/contract-agreement-message.json) to the `negotiations/:id/agreement` callback to create an agreement. If the
 negotiation state is successfully transitioned, the consumer must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.
@@ -239,17 +286,17 @@ Authorization: ...
 }
 ```
 
-### 3.4 The consumer `negotiations/:id/events` resource
+### 3.5 The consumer `negotiations/:id/events` resource
 
-#### 3.4.1 POST
+#### 3.5.1 POST
 
 A provider can POST a [ContractNegotiationEventMessage](./message/contract-negotiation-event-message.json) to the `negotiations/:id/events` callback with an `eventType`
 of `FINALIZED` to finalize a contract agreement. If the negotiation state is successfully transitioned, the consumer must return HTTP code 200 (OK). The response body is not
 specified and clients are not required to process it. 
 
-### 3.5 The consumer `negotiations/:id/termination` resource
+### 3.6 The consumer `negotiations/:id/termination` resource
 
-#### 3.5.1 POST
+#### 3.6.1 POST
 
 The provider connector can POST a [ContractNegotiationTerminationMessage](./message/contract-negotiation-termination-message.json) to terminate a negotiation. If the negotiation
 state is successfully transitioned, the consumer must return HTTP code 200 (OK). The response body is not specified and clients are not required to process it.
diff --git a/negotiation/contract.negotiation.protocol.md b/negotiation/contract.negotiation.protocol.md
index 7f18d610..94bb35d0 100644
--- a/negotiation/contract.negotiation.protocol.md
+++ b/negotiation/contract.negotiation.protocol.md
@@ -100,6 +100,9 @@ The `ContractRequestMessage` is sent by a consumer to initiate a contract negoti
 
 The `ContractOfferMessage` is sent by a provider to initiate a contract negotiation.
 
+#### Notes
+
+- The dataset id is not required but can be included when the provider initiates a contract negotiation.
 
 ### 3. ContractAgreementMessage