docs: adds documentations for the new management api

docs/samples/management-api-v2-walkthrough/1-management-api-oveview.md

@@ -0,0 +1,67 @@
+# 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`    |
+
+> Please note: The old Management API is now deprecated and is not tested for compliance. The `/v2` prefix is only a temporary part of the path and will be discarded once the migration to the new protocol is finished and the old API is taken out of service. Once that is done, the new management API can be reached through `MANAGEMENT_URL`.
+
+## 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)

docs/samples/management-api-v2-walkthrough/2-assets.md

@@ -0,0 +1,83 @@
+# Creating an Asset
+
+## Old plain JSON Schema
+
+```json
+{
+  "asset": {
+    "id": "asset-id",
+    "properties": {
+      "name": "asset-name",
+      "description": "asset-description",
+      "version": "0.0.1",
+      "contenttype": "application/json"
+    }
+  },
+  "dataAddress": {
+    "type": "asset-address-type",
+    "keyName": "asset-key-name"
+  }
+}
+```
+
+## 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": "0.0.1",
+      "contenttype": "application/json"
+    },
+    "privateProperties": {
+      "pvt-prop-1": "prt-prov-val-1",
+      "pvt-prop-2": "prt-prov-val-2"
+    }
+  },
+  "dataAddress": {
+    "type": "asset-address-type",
+    "keyName": "asset-key-name"
+  }
+}
+```
+
+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.
+
+## 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": "asset-address-type",
+                "keyName": "asset-key-name"
+              }
+            }' \
+    -s -o /dev/null -w 'Response Code: %{http_code}\n'
+```

docs/samples/management-api-v2-walkthrough/3-policy-definitions.md

@@ -0,0 +1,97 @@
+# Creating a Policy Definition
+
+## Old plain JSON Schema
+
+```json
+{
+  "id": "policy-definition-id",
+  "policy": {
+    "permissions": [
+      {
+        "action": {
+          "type": "USE"
+        },
+        "constraints": [
+          {
+            "leftExpression": {
+              "value": "BusinessPartnerNumber"
+            },
+            "rightExpression": {
+              "value": "BPN"
+            },
+            "operator": "EQ"
+          }
+        ]
+      }
+    ],
+    "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": "BusinessPartnerNumber",
+            "odrl:operator": "EQ",
+            "odrl:rightOperand":  "BPN"
+          }]
+      }
+    ],
+    "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'
+```

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": "policy-id",
+  "contractPolicyId": "policy-id",
+  "assetsSelector": [
+    {
+      "operandLeft": "id",
+      "operator": "=",
+      "operandRight": "asset-id"
+    }
+  ]
+}
+```
+
+## 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": "policy-id",
+  "contractPolicyId": "policy-id",
+  "assetsSelector": [
+    {
+      "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id",
+      "operator": "=",
+      "operandRight": "asset-id"
+    }
+  ]
+}
+```
+
+## 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'
+```

docs/samples/management-api-v2-walkthrough/5-catalog.md

@@ -0,0 +1,45 @@
+# Fetching provider's Catalog
+
+## Old plain JSON Schema
+
+```json
+{
+  "protocol" : "ids-protocol-http",
+  "providerUrl": "http://provider-control-plane:8282/api/v1/ids",
+  "querySpec": null
+}
+```
+
+## 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": "http://provider-control-plane:8282/api/v1/dsp",
+  "querySpec": null
+}
+```
+
+## Request
+
+In this case we fetch a provider catalog without using `queryspec`.
+
+```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": null
+            }' \
+    -s -o /dev/null -w 'Response Code: %{http_code}\n'
+```