eclipse-tractusx · yurimssilva · Jun 9, 2023 · Jun 9, 2023 · Jun 12, 2023 · Jun 19, 2023
diff --git a/docs/samples/management-api-v2-walkthrough/1-management-api-oveview.md b/docs/samples/management-api-v2-walkthrough/1-management-api-oveview.md
@@ -0,0 +1,65 @@
+# Management API V2 Overview
+
+## Introduction
+
+With the introduction of the new [Dataspace Protocol](https://docs.internationaldataspaces.org/dataspace-protocol/overview/readme), now using JSON-LD, all Management API endpoints had to be adapted as well to reflect that.
+JSON-LD (JSON for Linked Data) is an extension of JSON that introduces a set of principles and mechanisms to enable interoperability.
+
+This document will showcase how this change impacts the management API usage.
+
+> Please note: Before running the examples the corresponding environment variables must be set.
+> How such an environment can be setup locally is documented in [settings changes](../../migration/Version_0.3.4_0.4.0.md).
+
+## 1. Modified Endpoints
+
+The `MANAGEMENT_URL` specifies the URL of the management API and the prefix `v2` allows access to the functionality of the new management API.
+
+| Resource              | Endpoint                                   |
+|-----------------------|--------------------------------------------|
+| Asset                 | `<MANAGEMENT_URL>/v2/assets`               |
+| Policy Definition     | `<MANAGEMENT_URL>/v2/policydefinitions`    |
+| Contract Definition   | `<MANAGEMENT_URL>/v2/contractdefinitions`  |
+| Catalog               | `<MANAGEMENT_URL>/v2/catalog`              |
+| Contract Negotiation  | `<MANAGEMENT_URL>/v2/contractnegotiations` |
+| Contract Agreement    | `<MANAGEMENT_URL>/v2/contractagreements`   |
+| Transfer Process      | `<MANAGEMENT_URL>/v2/transferprocesses`    |
+
+## 2. Brief JSON-LD Introduction
+
+JSON-LD includes several important keywords that play a crucial role in defining the structure, semantics, and relationships within a JSON-LD document. Since some keys which are required in requests for the new management API aren't self-explanatory when you first see them, here are some of the most commonly used and important keywords in JSON-LD.
+These keys are generally part of the JSON-LD spec and serve as identification on a larger scope. Please also refer to the [JSON-LD spec](https://www.w3.org/TR/json-ld11/).
+
+### Keywords
+
+| Key       | Description                                                                                                                                                                                               |
+|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| @context  | Specifies the context for interpreting the meaning of terms and properties within a JSON-LD document. It associates terms with namespaces, vocabularies, or URLs.                                         |
+| @vocab    | Sets a default namespace or vocabulary for expanding terms within a JSON-LD document. It allows for a more concise representation of properties by omitting the namespace prefix for commonly used terms. |
+| @id       | Represents the unique identifier (URI or IRI) for a node or resource within a JSON-LD document. It allows for linking and referencing resources.                                                          |
+| @type     | Indicates the type(s) of a node or resource. It is used to specify the class or classes that the resource belongs to, typically using terms from a vocabulary or ontology.                                |
+
+### Namespaces
+
+A namespace is defined by associating a prefix with a URI or IRI in the @context of a JSON-LD document. The prefix is typically a short string, while the URI or IRI represents a namespace or vocabulary where the terms or properties are defined.
+
+| Key    | Description                                                                                                                                                                                                       |
+|--------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| dct    | Defines the prefix "dct" and associates it with the URI "https://purl.org/dc/terms/". The prefix "dct" can now be used in the JSON-LD document to represent terms from the Dublin Core Metadata Terms vocabulary. |
+| edc    | Defines the prefix "edc" and associates it with the URI "https://w3id.org/edc/v0.0.1/ns/". The prefix "edc" can now be used to represent terms from the EDC (Eclipse Dataspace Connect) vocabulary.               |
+| dcat   | Defines the prefix "dcat" and associates it with the URI "https://www.w3.org/ns/dcat/". The prefix "dcat" can now be used to represent terms from the DCAT (Data Catalog Vocabulary) vocabulary.                  |
+| odrl   | Defines the prefix "odrl" and associates it with the URI "http://www.w3.org/ns/odrl/2/". The prefix "odrl" can now be used to represent terms from the ODRL (Open Digital Rights Language) vocabulary.            |
+| dspace | Defines the prefix "dspace" and associates it with the URI "https://w3id.org/dspace/v0.8/". The prefix "dspace" can now be used to represent terms from the DSpace vocabulary.                                    |
+
+> Please note: The namespace `edc` currently is only a placeholder and does not lead to any JSON-LD context definition or vocabulary.
+> This will change at a later date.
+
+## 3. Walkthrough
+
+An additional collection of examples can be tried out using the updated [postman collection](../../development/postman/collection.json).
+
+1. [Create an Asset](2-assets.md)
+2. [Create a Policy Definition](3-policy-definitions.md)
+3. [Create Contract Definition](4-contract-definitions.md)
+4. [Fetch provider's Catalog](5-catalog.md)
+5. [Initiate Contract Negotiation](6-contract-negotiation.md)
+6. [Initiate Transfer Process](7-transfer-process.md)
diff --git a/docs/samples/management-api-v2-walkthrough/2-assets.md b/docs/samples/management-api-v2-walkthrough/2-assets.md
@@ -0,0 +1,84 @@
+# Creating an Asset
+
+## Old plain JSON Schema
+
+```json
+{
+  "asset": {
+    "id": "<ASSET-ID>",
+    "properties": {
+      "name": "<ASSET-NAME>",
+      "description": "<ASSET-DESCRIPTION>",
+      "version": "<ASSET-VERSION>",
+      "contenttype": "<ASSET-CONTENT-TYPE>"
+    }
+  },
+  "dataAddress": {
+    "properties": {
+      "type": "<SUPPORTED-TYPE>"
+    }
+  }
+}
+```
+
+## New JSON-LD Document
+
+> Please note: In our samples, properties **WILL NOT** be explicitly namespaced, and internal nodes **WILL NOT** be typed, relying on `@vocab` prefixing and root schema type inheritance respectively.
+
+```json
+{
+  "@context": {
+    "@vocab": "https://w3id.org/edc/v0.0.1/ns/"
+  },
+  "@type": "AssetEntryDto",
+  "asset": {
+    "@id": "<ASSET-ID>",
+    "properties": {
+      "name": "<ASSET-NAME>",
+      "description": "<ASSET-DESCRIPTION>",
+      "version": "<ASSET-VERSION>",
+      "contenttype": "<ASSET-CONTENT-TYPE>"
+    },
+    "privateProperties": {
+      "private-property": "<PRIVATE-PROPERTY-VALUE>",
+    }
+  },
+  "dataAddress": {
+    "type": "<SUPPORTED-TYPE>"
+  }
+}
+```
+
+A new addition are the `privateProperties`.
+Private properties will not be sent through the dataplane and are only accessible via the management API.
+This enables the storage of additional information pertaining the asset, that is not relevant for the consumer, but is nonetheless useful for the provider.
+Private properties are stores inside the `privateProperties` field.
+
+> Please note:
+> `privateProperties` are entirely optional and the field is not required for creating or updating an asset.
+> `dataAddress` should correspond to one of the supported types by the connector, e.g. HttpData and AmazonS3, and it should include all the necessary properties associated with the chosen type.
+
+## Request
+
+In this case we generate a very simple asset, that only contains the minimum in terms of information.
+For this we need both an asset and a data address, which together form an asset entry.
+
+```bash
+curl -X POST "${MANAGEMENT_URL}/v2/assets" \
+    --header 'X-Api-Key: password' \
+    --header 'Content-Type: application/json' \
+    --data '{
+              "@context": {
+                "@vocab": "https://w3id.org/edc/v0.0.1/ns/"
+              },
+              "@type": "AssetEntryDto",
+              "asset": {
+                "@id": "asset-id"
+              },
+              "dataAddress": {
+                "type": "HttpData",
+                "baseUrl": "https://jsonplaceholder.typicode.com/todos"
+              }
+            }' \
+    -s -o /dev/null -w 'Response Code: %{http_code}\n'
+```
diff --git a/docs/samples/management-api-v2-walkthrough/3-policy-definitions.md b/docs/samples/management-api-v2-walkthrough/3-policy-definitions.md
@@ -0,0 +1,98 @@
+# Creating a Policy Definition
+
+## Old plain JSON Schema
+
+```json
+{
+  "id": "<POLICY-DEFINITION-ID>",
+  "policy": {
+    "permissions": [
+      {
+        "action": {
+          "type": "USE"
+        },
+        "constraints": [
+          {
+            "leftExpression": {
+              "value": "<LEFT-EXPRESSION-VALUE>"
+            },
+            "rightExpression": {
+              "value": "<RIGHT-EXPRESSION-VALUE>"
+            },
+            "operator": "<OPERATOR>"
+          }
+        ]
+      }
+    ],
+    "prohibition": [],
+    "obligation": []
+  }
+}
+```
+
+## New JSON-LD Document
+
+Policy model is now pure [ODRL (Open Digital Rights Language)](https://www.w3.org/TR/odrl-model/) and going through it would help get a more complete picture.
+
+> Please note: In our samples, except from `odrl` vocabulary terms that must override `edc` default prefixing, properties **WILL NOT** be explicitly namespaced, and internal nodes **WILL NOT** be typed, relying on `@vocab` prefixing and root schema type inheritance respectively.
+
+```json
+{
+  "@context": {
+    "@vocab": "https://w3id.org/edc/v0.0.1/ns/",
+    "odrl": "http://www.w3.org/ns/odrl/2/"
+  },
+  "@type":"PolicyDefinition",
+  "@id": "<POLICY-DEFINITION-ID>",
+  "policy": {
+    "odrl:permission": [
+      {
+        "odrl:action": "USE",
+        "odrl:constraint": [
+          {
+            "odrl:leftOperand": "<LEFT-OPERAND>",
+            "odrl:operator": "<OPERATOR>",
+            "odrl:rightOperand":  "<RIGHT-OPERAND>"
+          }]
+      }
+    ],
+    "odrl:prohibition": [],
+    "odrl:obligation": []
+  }
+}
+```
+
+## Request
+
+In this case we generate a very simple policy definition, that only contains the minimum in terms of information.
+A Policy MUST have at least one permission, prohibition, or obligation property value of type Rule and in our case it will hold a permission defining our well-known `BusinessPartnerNumber` validation `Constraint`.
+
+```bash
+curl -X POST "${MANAGEMENT_URL}/v2/policydefinitions" \
+    --header 'X-Api-Key: password' \
+    --header 'Content-Type: application/json' \
+    --data '{
+              "@context": {
+                "@vocab": "https://w3id.org/edc/v0.0.1/ns/",
+                "odrl": "http://www.w3.org/ns/odrl/2/"
+              },
+              "@type":"PolicyDefinition",
+              "@id": "policy-definition-id",
+              "policy": {
+                "odrl:permission": [
+                  {
+                    "odrl:action": "USE",
+                    "odrl:constraint": [
+                      {
+                        "odrl:leftOperand": "BusinessPartnerNumber",
+                        "odrl:operator": "eq",
+                        "odrl:rightOperand":  "BPN"
+                      }]
+                  }
+                ],
+                "odrl:prohibition": [],
+                "odrl:obligation": []
+              }
+            }' \
+    -s -o /dev/null -w 'Response Code: %{http_code}\n'
+```
diff --git a/docs/samples/management-api-v2-walkthrough/4-contract-definitions.md b/docs/samples/management-api-v2-walkthrough/4-contract-definitions.md
@@ -0,0 +1,70 @@
+# Creating a Contract Definition
+
+## Old plain JSON Schema
+
+```json
+{
+  "id": "<CONTRACT-DEFINITION-ID>",
+  "accessPolicyId": "<ACCESS-POLICY-ID>",
+  "contractPolicyId": "<CONTRACT-POLICY-ID>",
+  "assetsSelector": [
+    {
+      "operandLeft": "<OPERAND-LEFT>",
+      "operator": "<OPERATOR>",
+      "operandRight": "<OPERAND-RIGHT>"
+    }
+  ]
+}
+```
+
+## New JSON-LD Document
+
+> Please note: In our samples, properties **WILL NOT** be explicitly namespaced, and internal nodes **WILL NOT** be typed, relying on `@vocab` prefixing and root schema type inheritance respectively.
+
+```json
+{
+  "@context": {
+    "@vocab": "https://w3id.org/edc/v0.0.1/ns/"
+  },
+  "@type": "ContractDefinition",
+  "@id": "<CONTRACT-DEFINITION-ID>",
+  "accessPolicyId": "<ACCESS-POLICY-ID>",
+  "contractPolicyId": "<CONTRACT-POLICY-ID>",
+  "assetsSelector": [
+    {
+      "operandLeft": "<OPERAND-LEFT>",
+      "operator": "<OPERATOR>",
+      "operandRight": "<OPERAND-RIGHT>"
+    }
+  ]
+}
+```
+
+## Request
+
+In this case we generate a very simple contract definition, that only contains the minimum in terms of information.
+A Contract Definition MUST have `accessPolicy`, `contractPolicy` identifiers and `assetsSelector`property values.
+The `operandLeft` property value MUST contain the asset property full qualified term `<vocabulary-uri>/<term>`, in our case `https://w3id.org/edc/v0.0.1/ns/id`.
+
+```bash
+curl -X POST "${MANAGEMENT_URL}/v2/contractdefinitions" \
+    --header 'X-Api-Key: password' \
+    --header 'Content-Type: application/json' \
+    --data '{
+              "@context": {
+                "@vocab": "https://w3id.org/edc/v0.0.1/ns/"
+              },
+              "@type": "ContractDefinition",
+              "@id": "contract-definition-id",
+              "accessPolicyId": "policy-id,
+              "contractPolicyId": "policy-id",
+              "assetsSelector": [
+                {
+                  "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id",
+                  "operator": "=",
+                  "operandRight": "asset-id"
+                }
+              ]
+            }' \
+    -s -o /dev/null -w 'Response Code: %{http_code}\n'
+```
diff --git a/docs/samples/management-api-v2-walkthrough/5-catalog.md b/docs/samples/management-api-v2-walkthrough/5-catalog.md
@@ -0,0 +1,66 @@
+# Fetching provider's Catalog
+
+## Old plain JSON Schema
+
+```json
+{
+  "protocol" : "ids-protocol-http",
+  "providerUrl": "<PROVIDER-URL>",
+  "querySpec": {
+    "offset": 0,
+    "limit": 100,
+    "filter": "",
+    "range": {
+      "from": 0,
+      "to": 100
+    },
+    "sortField": "",
+    "criterion": ""
+  }
+}
+```
+
+## New JSON-LD Document
+
+> Please note: In our samples, properties **WILL NOT** be explicitly namespaced, and internal nodes **WILL NOT** be typed, relying on `@vocab` prefixing and root schema type inheritance respectively.
+
+```json
+{
+  "@context": {
+    "@vocab": "https://w3id.org/edc/v0.0.1/ns/"
+  },
+  "protocol" : "dataspace-protocol-http",
+  "providerUrl": "<PROVIDER-URL>",
+  "querySpec": {
+    "offset": 0,
+    "limit": 100,
+    "filterExpression": {
+      "operandLeft": "<OPERAND-LEFT>",
+      "operator": "<OPERATOR>",
+      "operandRight": "<OPERAND-RIGHT>"
+    }
+  }
+}
+```
+
+## Request
+
+In this case we fetch a provider catalog.
+
+```bash
+curl -X POST "${MANAGEMENT_URL}/v2/catalog/request" \
+    --header 'X-Api-Key: password' \
+    --header 'Content-Type: application/json' \
+    --data '{
+              "@context": {
+                "vocab": "https://w3id.org/edc/v0.0.1/ns/"
+              },
+              "protocol" : "dataspace-protocol-http",
+              "providerUrl": "http://provider-control-plane:8282/api/v1/dsp",
+              "querySpec": {
+                "offset": 0,
+                "limit": 100
+              }
+            }' \
+    -s -o /dev/null -w 'Response Code: %{http_code}\n'
+```