Update management api walkthrough

eclipse-tractusx · Apr 19, 2024 · 6ef792f · 6ef792f
1 parent 49b9de5
commit 6ef792f
Show file tree

Hide file tree

Showing 10 changed files with 91 additions and 81 deletions.
diff --git a/DEPENDENCIES b/DEPENDENCIES
@@ -344,11 +344,11 @@ maven/mavencentral/org.apiguardian/apiguardian-api/1.1.2, Apache-2.0, approved,
 maven/mavencentral/org.assertj/assertj-core/3.25.3, Apache-2.0, approved, #12585
 maven/mavencentral/org.awaitility/awaitility/4.2.1, Apache-2.0, approved, #14178
 maven/mavencentral/org.bouncycastle/bcpkix-jdk18on/1.72, MIT, approved, #3789
-maven/mavencentral/org.bouncycastle/bcpkix-jdk18on/1.78, MIT, approved, #14235
+maven/mavencentral/org.bouncycastle/bcpkix-jdk18on/1.78, MIT, approved, #14434
 maven/mavencentral/org.bouncycastle/bcprov-jdk18on/1.72, MIT AND CC0-1.0, approved, #3538
 maven/mavencentral/org.bouncycastle/bcprov-jdk18on/1.78, MIT AND CC0-1.0, approved, #14433
 maven/mavencentral/org.bouncycastle/bcutil-jdk18on/1.72, MIT, approved, #3790
-maven/mavencentral/org.bouncycastle/bcutil-jdk18on/1.78, MIT, approved, #14238
+maven/mavencentral/org.bouncycastle/bcutil-jdk18on/1.78, MIT, approved, #14435
 maven/mavencentral/org.ccil.cowan.tagsoup/tagsoup/1.2.1, Apache-2.0, approved, clearlydefined
 maven/mavencentral/org.checkerframework/checker-qual/3.12.0, MIT, approved, clearlydefined
 maven/mavencentral/org.checkerframework/checker-qual/3.42.0, MIT, approved, clearlydefined

diff --git a/docs/usage/management-api-walkthrough/01_assets.md b/docs/usage/management-api-walkthrough/01_assets.md
@@ -4,7 +4,7 @@ An Asset is the fundamental representation of an arbitrary backend interface in
 with its Control Plane as a first step to expose it to the Dataspace via the Dataplane later on. This registration is
 executed via the following Request:
 
-```http
+```http request
 POST /v3/assets HTTP/1.1
 Host: https://provider-control.plane/api/management
 X-Api-Key: password
@@ -15,19 +15,21 @@ Content-Type: application/json
 {
   "@context": {
     "@vocab": "https://w3id.org/edc/v0.0.1/ns/",
-    "dct": "https://purl.org/dc/terms/"
+    "dct": "http://purl.org/dc/terms/"
+  },
+  "@type": "Asset",
+  "@id": "{{ASSET_ID}}",
+  "dataAddress": {
+    "@type": "DataAddress",
+    "type": "{{SUPPORTED_TYPE}}"
   },
-  "@id": "<ASSET-ID>",
   "properties": {
     "dct:type": {
       "@id": "https://my-namespa.ce/my-asset-type"
     }
   },
   "privateProperties": {
-    "private-property": "<PRIVATE-PROPERTY-VALUE>"
-  },
-  "dataAddress": {
-    "type": "<SUPPORTED-TYPE>"
+    "private-property": "{{PRIVATE-PROPERTY-VALUE}}"
   }
 }
 ```
@@ -59,11 +61,12 @@ request will be manipulated by the Data Plane - to what degree depends on the co
 ```json
 {
   "@context": {
-    "edc": "https://w3id.org/edc/v0.0.1/ns/",
+    "@vocab": "https://w3id.org/edc/v0.0.1/ns/",
     "cx-common": "https://w3id.org/catenax/ontology/common#",
     "cx-taxo": "https://w3id.org/catenax/taxonomy#",
-    "dct": "https://purl.org/dc/terms/"
+    "dct": "http://purl.org/dc/terms/"
   },
+  "@type": "Asset",
   "@id": "{% uuid 'v4' %}",
   "properties": {
     "dct:type": {

diff --git a/docs/usage/management-api-walkthrough/02_policies.md b/docs/usage/management-api-walkthrough/02_policies.md
@@ -27,8 +27,8 @@ impacting policy definitions.
 
 Policies can be created in the EDC as follows:
 
-```http
-POST /v3/policydefinitions HTTP/1.1
+```http request
+POST /v2/policydefinitions HTTP/1.1
 Host: https://provider-control.plane/api/management
 X-Api-Key: password
 Content-Type: application/json
@@ -330,7 +330,7 @@ that the EDC interprets policies it can't evaluate as true by default. A couple
   "@context": {
     "odrl": "http://www.w3.org/ns/odrl/2/"
   },
-  "@type": "PolicyDefinitionRequest",
+  "@type": "PolicyDefinition",
   "@id": "{% uuid 'v4' %}",
   "policy": {
     "@type": "Policy",
@@ -477,8 +477,8 @@ Example:
 {
   "@context": "http://www.w3.org/ns/odrl.jsonld",
   "@type": "Set",
-  "@id": "<ID_SET_BY_CLIENT>",
-  "target": "<ID_OF_TARGET_DATASET>",
+  "@id": "{{ID_SET_BY_CLIENT}}",
+  "target": "{{ID_OF_TARGET_DATASET}}",
   "permission": [
     {
       "action": "use"

diff --git a/docs/usage/management-api-walkthrough/03_contractdefinitions.md b/docs/usage/management-api-walkthrough/03_contractdefinitions.md
@@ -4,7 +4,7 @@ A Contract Definition is the connection between a set of [Assets](01_assets.md)
 Policy. The two policies are both policies as explained [previously](02_policies.md) but checked in different
 stages of communication between Data Provider and Data Consumer. The creation request looks like this:
 
-```http
+```http request
 POST /v2/contractdefinitions HTTP/1.1
 Host: https://provider-control.plane/api/management
 X-Api-Key: password
@@ -22,6 +22,7 @@ Content-Type: application/json
   "contractPolicyId": "myContractPolicyId",
   "assetsSelector": 
     {
+      "@type": "CriterionDto",
       "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id",
       "operator": "=",
       "operandRight": "myAssetId"
@@ -52,6 +53,7 @@ to match multiple Assets if they share a common property:
 ```json
 {
   "assetsSelector": {
+    "@type": "Criterion",
     "operandLeft": "https://w3id.org/edc/v0.0.1/ns/myCommonProperty",
     "operator": "=",
     "operandRight": "sharedValue"
@@ -64,11 +66,13 @@ These can also be chained together with a logical AND:
 {
   "assetsSelector": [
     {
+      "@type": "Criterion",
       "operandLeft": "https://w3id.org/edc/v0.0.1/ns/myCommonProperty",
       "operator": "=",
       "operandRight": "sharedValue"
     },
     {
+      "@type": "Criterion",
       "operandLeft": "https://w3id.org/edc/v0.0.1/ns/myOtherProperty",
       "operator": "=",
       "operandRight": "otherSharedValue"

diff --git a/docs/usage/management-api-walkthrough/04_catalog.md b/docs/usage/management-api-walkthrough/04_catalog.md
@@ -4,7 +4,7 @@ The catalog API is the first request in this sequence that passes through the Da
 Consumer against their own Control Plane and triggers the retrieval of a catalog from a specified Data Provider. The request
 looks like this:
 
-```http
+```http request
 POST /v2/catalog/request HTTP/1.1
 Host: https://consumer-control.plane/api/management
 X-Api-Key: password
@@ -13,17 +13,18 @@ Content-Type: application/json
 ```json
 {
   "@context": {
-    "edc": "https://w3id.org/edc/v0.0.1/ns/",
-    "@vocab": "https://w3id.org/edc/v0.0.1/ns/"
+    "@vocab": "https://w3id.org/edc/v0.0.1/ns/",
+    "odrl": "http://www.w3.org/ns/odrl/2/"
   },
   "@type": "CatalogRequest",
+  "counterPartyId": "<string>",
   "counterPartyAddress": "https://provider-control.plane/api/v1/dsp",
-  "counterPartyId": "<PROVIDER-BPN>",
   "protocol": "dataspace-protocol-http",
   "querySpec": {
+    "@type": "QuerySpec",
     "offset": 0,
     "limit": 50,
-    "sortField": "https://purl.org/dc/terms/type",
+    "sortField": "http://purl.org/dc/terms/type",
     "sortOrder": "ASC",
     "filterExpression": [
       {
@@ -70,7 +71,7 @@ The returned payload is a `dcat:Catalog` as required by the [DSP-Specification v
   "@type": "dcat:Catalog",
   "dspace:participantId": "BPNL000000001INT",
   "dcat:dataset": {
-    "@id": "<ASSET-ID>",
+    "@id": "{{ASSET_ID}}",
     "@type": "dcat:Dataset",
     "odrl:hasPolicy": {
       "@id": "MQ==:MQ==:M2ZmZDRhY2MtMzkyNy00NGI4LWJlZDItNDcwY2RiZGRjN2Ex",
@@ -139,7 +140,7 @@ The returned payload is a `dcat:Catalog` as required by the [DSP-Specification v
     "dct:terms": "connector",
     "dct:endpointUrl": "http://provider-data.plane/api/v1/dsp"
   },
-  "participantId": "<PROVIDER-BPN>",
+  "participantId": "{{PROVIDER_BPN}}",
   "@context": {
     "@vocab": "https://w3id.org/edc/v0.0.1/ns/",
     "edc": "https://w3id.org/edc/v0.0.1/ns/",

diff --git a/docs/usage/management-api-walkthrough/05_contractnegotiations.md b/docs/usage/management-api-walkthrough/05_contractnegotiations.md
@@ -10,7 +10,7 @@ It includes
 
 To trigger the process, the Data Consumer POSTs against their own Control Plane.
 
-```http
+```http request
 POST /v2/contractnegotiations HTTP/1.1
 Host: https://consumer-control.plane/api/management
 X-Api-Key: password
@@ -20,16 +20,16 @@ Content-Type: application/json
 ```json
 {
   "@context": {
-    "edc": "https://w3id.org/edc/v0.0.1/ns/"
+    "@vocab": "https://w3id.org/edc/v0.0.1/ns/"
   },
   "@type": "ContractRequest",
   "counterPartyAddress": "https://provider-control.plane/api/v1/dsp",
   "protocol": "dataspace-protocol-http",
   "policy": {
-    "@id": "<OFFER_ID>",
     "@type": "Offer",
-    "target": "<ASSET_ID>",
-    "assigner": "<PROVIDER_BPN>",
+    "@id": "{{OFFER_ID}}",
+    "target": "{{ASSET_ID}}",
+    "assigner": "{{PROVIDER_BPN}}",
     "permission": [],
     "prohibition": [],
     "obligation": []
@@ -46,7 +46,6 @@ Content-Type: application/json
     }
   ]
 }
-
 ```
 - `counterPartyAddress` sets the coordinates for the connector that the Consumer-EDC shall negotiate with (Provider EDC).
   It will usually end in `/api/v1/dsp`
@@ -92,7 +91,7 @@ the `@id` property.
 
 ### Polling
 
-```http
+```http request
 GET /v2/contractnegotiation/773b8795-45f2-4c57-a020-dc04e639baf3 HTTP/1.1
 Host: https://consumer-control.plane/api/management
 X-Api-Key: password
@@ -109,7 +108,7 @@ that will look like this:
   "type": "CONSUMER",
   "protocol": "dataspace-protocol-http",
   "state": "REQUESTING",
-  "counterPartyId": "<PROVIDER_BPN>",
+  "counterPartyId": "{{PROVIDER_BPN}}",
   "counterPartyAddress": "https://provider-control.plane/api/v1/dsp",
   "callbackAddresses": [
     {
@@ -154,8 +153,8 @@ Here's an example:
   "at": 1701441001897,
   "payload": {
     "contractNegotiationId": "019488e0-f242-4c12-8314-610927b09e96",
-    "counterPartyAddress": "<PROVIDER-CONTROLPLANE-DSP-ENDPOINT>",
-    "counterPartyId": "<PROVIDER-BPN>",
+    "counterPartyAddress": "{{PROVIDER_CONTROLPLANE_DSP_ENDPOINT}}",
+    "counterPartyId": "{{PROVIDER_BPN}}",
     "callbackAddresses": [
       {
         "transactional": false,
@@ -169,12 +168,12 @@ Here's an example:
     ],
     "contractOffers": [
       {
-        "id": "<OFFER-ID>",
+        "id": "{{OFFER_ID}}",
         "policy": {
           "permissions": [
             {
               "edctype": "dataspaceconnector:permission",
-              "target": "<ASSET-ID>",
+              "target": "{{ASSET_ID}}",
               "action": {
                 "type": "http://www.w3.org/ns/odrl/2/use",
                 "includedIn": null,
@@ -192,22 +191,22 @@ Here's an example:
           "inheritsFrom": null,
           "assigner": null,
           "assignee": null,
-          "target": "<ASSET-ID>",
+          "target": "{{ASSET_ID}}",
           "@type": {
             "@policytype": "set"
           }
         },
-        "assetId": "<ASSET-ID>"
+        "assetId": "{{ASSET_ID}}"
       }
     ],
     "protocol": "dataspace-protocol-http",
     "lastContractOffer": {
-      "id": "<OFFER-ID>",
+      "id": "{{OFFER_ID}}",
       "policy": {
         "permissions": [
           {
             "edctype": "dataspaceconnector:permission",
-            "target": "<ASSET-ID>",
+            "target": "{{ASSET_ID}}",
             "action": {
               "type": "http://www.w3.org/ns/odrl/2/use",
               "includedIn": null,
@@ -225,12 +224,12 @@ Here's an example:
         "inheritsFrom": null,
         "assigner": null,
         "assignee": null,
-        "target": "<ASSET-ID>",
+        "target": "{{ASSET_ID}}",
         "@type": {
           "@policytype": "set"
         }
       },
-      "assetId": "<ASSET-ID>"
+      "assetId": "{{ASSET_ID}}"
     }
   },
   "type": "ContractNegotiationRequested"

diff --git a/docs/usage/management-api-walkthrough/06_transferprocesses.md b/docs/usage/management-api-walkthrough/06_transferprocesses.md
@@ -29,7 +29,7 @@ terminated/suspended or terminated by the policy monitor depending on the config
 ## Transfer Request
 
 To trigger this process, the Consumer app makes a request to its EDC's Control Plane:
-```http
+```http request
 POST /v2/transferprocesses HTTP/1.1
 Host: https://consumer-control.plane/api/management
 X-Api-Key: password
@@ -42,11 +42,11 @@ Content-Type: application/json
     "@vocab": "https://w3id.org/edc/v0.0.1/ns/"
   },
   "@type": "TransferRequest",
-  "assetId": "<ASSET-ID>",
-  "counterPartyAddress": "<CONNECTOR-ADDRESS>",
-  "contractId": "<CONTRACT-AGREEMENT-ID>",
+  "assetId": "{{ASSET_ID}}",
+  "contractId": "{{CONTRACT_AGREEMENT_ID}}",
+  "counterPartyAddress": "{{CONNECTOR_ADDRESS}}",
   "dataDestination": {
-    "type": "<SUPPORTED-TYPE>"
+    "type": "<supported-transfer-type>"
   },
   "privateProperties": {},
   "protocol": "dataspace-protocol-http",
@@ -61,7 +61,10 @@ Content-Type: application/json
       "authKey": "auth-key",
       "authCodeId": "auth-code-id"
     }
-  ]
+  ],
+  "privateProperties": {
+    "receiverHttpEndpoint": "{{RECEIVER_HTTP_ENDPOINT}}"
+  }
 }
 ```
 
@@ -106,7 +109,7 @@ the Consumer Control Plane. How to handle EDRs consumption check [here](07_edrs.
 
 The state of a given Transfer Process can be requested like this:
 
-```http
+```http request
 GET /v2/transferprocesses/177aba51-52d7-44dc-beab-fd6151147024 HTTP/1.1
 Host: https://consumer-control.plane/api/management
 X-Api-Key: password