chore: add http endpoint for provider initiated CN (International-Dat…

…a-Spaces-Association#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 <[email protected]>
jimmarino · Sep 7, 2023 · aff274d · aff274d
1 parent 2546b78
commit aff274d
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 7 deletions.
diff --git 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
@@ -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