From a444335380fc8c8e070d6e57391d64cd943972ca Mon Sep 17 00:00:00 2001 From: yurimssilva Date: Fri, 9 Jun 2023 14:13:51 +0100 Subject: [PATCH 1/6] docs: adds documentations for the new management api Co-authored-by: Sascha Isele --- .../1-management-api-oveview.md | 67 ++++++++++ .../management-api-v2-walkthrough/2-assets.md | 84 ++++++++++++ .../3-policy-definitions.md | 97 ++++++++++++++ .../4-contract-definitions.md | 70 ++++++++++ .../5-catalog.md | 45 +++++++ .../6-contract-negotiation.md | 124 ++++++++++++++++++ .../7-transfer-process.md | 89 +++++++++++++ 7 files changed, 576 insertions(+) create mode 100644 docs/samples/management-api-v2-walkthrough/1-management-api-oveview.md create mode 100644 docs/samples/management-api-v2-walkthrough/2-assets.md create mode 100644 docs/samples/management-api-v2-walkthrough/3-policy-definitions.md create mode 100644 docs/samples/management-api-v2-walkthrough/4-contract-definitions.md create mode 100644 docs/samples/management-api-v2-walkthrough/5-catalog.md create mode 100644 docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md create mode 100644 docs/samples/management-api-v2-walkthrough/7-transfer-process.md 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 new file mode 100644 index 000000000..10194ad56 --- /dev/null +++ b/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 | `/v2/assets` | +| Policy Definition | `/v2/policydefinitions` | +| Contract Definition | `/v2/contractdefinitions` | +| Catalog | `/v2/catalog` | +| Contract Negotiation | `/v2/contractnegotiations` | +| Contract Agreement | `/v2/contractagreements` | +| Transfer Process | `/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) diff --git a/docs/samples/management-api-v2-walkthrough/2-assets.md b/docs/samples/management-api-v2-walkthrough/2-assets.md new file mode 100644 index 000000000..dfa5fe80a --- /dev/null +++ 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": "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. + +> 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' +``` diff --git a/docs/samples/management-api-v2-walkthrough/3-policy-definitions.md b/docs/samples/management-api-v2-walkthrough/3-policy-definitions.md new file mode 100644 index 000000000..db76d7a72 --- /dev/null +++ b/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' +``` diff --git a/docs/samples/management-api-v2-walkthrough/4-contract-definitions.md b/docs/samples/management-api-v2-walkthrough/4-contract-definitions.md new file mode 100644 index 000000000..d02c34fb8 --- /dev/null +++ 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": "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 `/`, 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 new file mode 100644 index 000000000..00849d47c --- /dev/null +++ b/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' +``` diff --git a/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md b/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md new file mode 100644 index 000000000..8820bc20b --- /dev/null +++ b/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md @@ -0,0 +1,124 @@ +# Initiation a Contract Negotiation + +## Old plain JSON Schema + +```json +{ + "connectorAddress": "provider-dsp-url", + "protocol": "dataspace-protocol-http", + "connectorId": "provider-id", + "providerId": "provider-id", + "offer": { + "offerId": "offer-id", + "assetId": "asset-id", + "policy": { + "permissions": [ + { + "action": { + "type": "USE" + }, + "constraints": [ + { + "leftExpression": { + "value": "BusinessPartnerNumber" + }, + "rightExpression": { + "value": "BPN" + }, + "operator": "EQ" + } + ] + } + ], + "prohibition": [], + "obligation": [] + } + } +} +``` + +## 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/", + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@type": "NegotiationInitiateRequestDto", + "connectorAddress": "provider-dsp-url", + "protocol": "dataspace-protocol-http", + "connectorId": "provider-id", + "providerId": "provider-id", + "offer": { + "offerId": "offer-id", + "assetId": "asset-id", + "policy": { + "@type": "odrl:Set", + "odrl:permission": { + "odrl:target": "asset-id", + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": "EQ", + "odrl:rightOperand": "BPN" + } + } + }, + "odrl:prohibition": [], + "odrl:obligation": [], + "odrl:target": "asset-id" + } + } +} +``` + +## Request + +In this case we initiate a contract negotiation with the provider. + +```bash +curl -X POST "${MANAGEMENT_URL}/v2/contractnegotiations" \ + --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": "NegotiationInitiateRequestDto", + "connectorAddress": "provider-dsp-url", + "protocol": "dataspace-protocol-http", + "connectorId": "provider-id", + "providerId": "provider-id", + "offer": { + "offerId": "offer-id", + "assetId": "asset-id", + "policy": { + "@type": "odrl:Set", + "odrl:permission": { + "odrl:target": "asset-id", + "odrl:action": { + "odrl:type": "USE" + }, + "odrl:constraint": { + "odrl:or": { + "odrl:leftOperand": "BusinessPartnerNumber", + "odrl:operator": "EQ", + "odrl:rightOperand": "ANY-BPN" + } + } + }, + "odrl:prohibition": [], + "odrl:obligation": [], + "odrl:target": "asset-id" + } + } + }' \ + -s -o /dev/null -w 'Response Code: %{http_code}\n' +``` diff --git a/docs/samples/management-api-v2-walkthrough/7-transfer-process.md b/docs/samples/management-api-v2-walkthrough/7-transfer-process.md new file mode 100644 index 000000000..d74357ed2 --- /dev/null +++ b/docs/samples/management-api-v2-walkthrough/7-transfer-process.md @@ -0,0 +1,89 @@ +# Initiation a Transfer Process + +## Old plain JSON Schema + +```json +{ + "assetId": "asset-id", + "connectorAddress": "provider-dsp-url", + "contractId": "contract-agreement-id", + "dataDestination": { + "properties": { + "type": "HttpProxy" + } + }, + "managedResources": false, + "privateProperties": { + "receiverHttpEndpoint": "backend-service-endpoint" + }, + "protocol": "ids-protocol-http", + "transferType": { + "contentType": "application/octet-stream", + "isFinite": true + } +} +``` + +## 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/", + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "assetId": "asset-id", + "connectorAddress": "provider-dsp-url", + "contractId": "contract-agreement-id", + "dataDestination": { + "properties": { + "type": "HttpProxy" + } + }, + "managedResources": false, + "privateProperties": { + "receiverHttpEndpoint": "backend-service-endpoint" + }, + "protocol": "dataspace-protocol-http", + "transferType": { + "contentType": "application/octet-stream", + "isFinite": true + } +} +``` + +## Request + +In this case we initiate a transfer process with the provider. + +```bash +curl -X POST "${MANAGEMENT_URL}/v2/transferprocesses" \ + --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/" + }, + "assetId": "asset-id", + "connectorAddress": "provider-dsp-url", + "contractId": "contract-agreement-id", + "dataDestination": { + "properties": { + "type": "HttpProxy" + } + }, + "managedResources": false, + "privateProperties": { + "receiverHttpEndpoint": "backend-service-endpoint" + }, + "protocol": "dataspace-protocol-http", + "transferType": { + "contentType": "application/octet-stream", + "isFinite": true + } + }' \ + -s -o /dev/null -w 'Response Code: %{http_code}\n' +``` From 73d8724364e9c9873d4580b588c8c461236d0fd7 Mon Sep 17 00:00:00 2001 From: yurimssilva Date: Mon, 12 Jun 2023 09:17:23 +0100 Subject: [PATCH 2/6] fix: markdownlint error reports --- docs/samples/management-api-v2-walkthrough/2-assets.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/samples/management-api-v2-walkthrough/2-assets.md b/docs/samples/management-api-v2-walkthrough/2-assets.md index dfa5fe80a..d05bf7c74 100644 --- a/docs/samples/management-api-v2-walkthrough/2-assets.md +++ b/docs/samples/management-api-v2-walkthrough/2-assets.md @@ -54,7 +54,6 @@ 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. > Please note: `privateProperties` are entirely optional and the field is not required for creating or updating an asset. From 15c99bd52b46a773e0c41e96001b029c3fe4db62 Mon Sep 17 00:00:00 2001 From: yurimssilva Date: Mon, 19 Jun 2023 19:04:54 +0100 Subject: [PATCH 3/6] refactor: updated api information and fixed json-ld schemas --- .../1-management-api-oveview.md | 4 +-- .../3-policy-definitions.md | 6 ++-- .../5-catalog.md | 36 +++++++++++++++++-- .../7-transfer-process.md | 8 ++--- 4 files changed, 39 insertions(+), 15 deletions(-) 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 index 10194ad56..ed70745a8 100644 --- a/docs/samples/management-api-v2-walkthrough/1-management-api-oveview.md +++ b/docs/samples/management-api-v2-walkthrough/1-management-api-oveview.md @@ -24,8 +24,6 @@ The `MANAGEMENT_URL` specifies the URL of the management API and the prefix `v2` | Contract Agreement | `/v2/contractagreements` | | Transfer Process | `/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. @@ -49,7 +47,7 @@ A namespace is defined by associating a prefix with a URI or IRI in the @context | 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. | +| 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. diff --git a/docs/samples/management-api-v2-walkthrough/3-policy-definitions.md b/docs/samples/management-api-v2-walkthrough/3-policy-definitions.md index db76d7a72..aaa207be3 100644 --- a/docs/samples/management-api-v2-walkthrough/3-policy-definitions.md +++ b/docs/samples/management-api-v2-walkthrough/3-policy-definitions.md @@ -19,7 +19,7 @@ "rightExpression": { "value": "BPN" }, - "operator": "EQ" + "operator": "eq" } ] } @@ -50,7 +50,7 @@ Policy model is now pure [ODRL (Open Digital Rights Language)](https://www.w3.or "odrl:constraint": [ { "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": "EQ", + "odrl:operator": "eq", "odrl:rightOperand": "BPN" }] } @@ -84,7 +84,7 @@ curl -X POST "${MANAGEMENT_URL}/v2/policydefinitions" \ "odrl:constraint": [ { "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": "EQ", + "odrl:operator": "eq", "odrl:rightOperand": "BPN" }] } diff --git a/docs/samples/management-api-v2-walkthrough/5-catalog.md b/docs/samples/management-api-v2-walkthrough/5-catalog.md index 00849d47c..79448ad6b 100644 --- a/docs/samples/management-api-v2-walkthrough/5-catalog.md +++ b/docs/samples/management-api-v2-walkthrough/5-catalog.md @@ -6,7 +6,17 @@ { "protocol" : "ids-protocol-http", "providerUrl": "http://provider-control-plane:8282/api/v1/ids", - "querySpec": null + "querySpec": { + "offset": 0, + "limit": 100, + "filter": "", + "range": { + "from": 0, + "to": 100 + }, + "sortField": "", + "criterion": "" + } } ``` @@ -21,7 +31,17 @@ }, "protocol" : "dataspace-protocol-http", "providerUrl": "http://provider-control-plane:8282/api/v1/dsp", - "querySpec": null + "querySpec": { + "offset": 0, + "limit": 100, + "filter": "", + "range": { + "from": 0, + "to": 100 + }, + "sortField": "", + "criterion": "" + } } ``` @@ -39,7 +59,17 @@ curl -X POST "${MANAGEMENT_URL}/v2/catalog/request" \ }, "protocol" : "dataspace-protocol-http", "providerUrl": "http://provider-control-plane:8282/api/v1/dsp", - "querySpec": null + "querySpec": { + "offset": 0, + "limit": 100, + "filter": "", + "range": { + "from": 0, + "to": 100 + }, + "sortField": "", + "criterion": "" + } }' \ -s -o /dev/null -w 'Response Code: %{http_code}\n' ``` diff --git a/docs/samples/management-api-v2-walkthrough/7-transfer-process.md b/docs/samples/management-api-v2-walkthrough/7-transfer-process.md index d74357ed2..2ed86900a 100644 --- a/docs/samples/management-api-v2-walkthrough/7-transfer-process.md +++ b/docs/samples/management-api-v2-walkthrough/7-transfer-process.md @@ -38,9 +38,7 @@ "connectorAddress": "provider-dsp-url", "contractId": "contract-agreement-id", "dataDestination": { - "properties": { - "type": "HttpProxy" - } + "type": "HttpProxy" }, "managedResources": false, "privateProperties": { @@ -71,9 +69,7 @@ curl -X POST "${MANAGEMENT_URL}/v2/transferprocesses" \ "connectorAddress": "provider-dsp-url", "contractId": "contract-agreement-id", "dataDestination": { - "properties": { - "type": "HttpProxy" - } + "type": "HttpProxy" }, "managedResources": false, "privateProperties": { From 54ecd6b6e1545941a81a18d35efd9c5b7c15fe3a Mon Sep 17 00:00:00 2001 From: yurimssilva Date: Thu, 22 Jun 2023 01:50:05 +0100 Subject: [PATCH 4/6] fix: md row format --- .../management-api-v2-walkthrough/1-management-api-oveview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index ed70745a8..fb7497131 100644 --- a/docs/samples/management-api-v2-walkthrough/1-management-api-oveview.md +++ b/docs/samples/management-api-v2-walkthrough/1-management-api-oveview.md @@ -48,7 +48,7 @@ A namespace is defined by associating a prefix with a URI or IRI in the @context | 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. | +| 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. From c21f953bd6587f339c465a1586aa1bc9eb307759 Mon Sep 17 00:00:00 2001 From: yurimssilva Date: Wed, 28 Jun 2023 23:28:59 +0100 Subject: [PATCH 5/6] fix: json value placeholders and information about dataAddress --- .../management-api-v2-walkthrough/2-assets.md | 39 +++++++------- .../3-policy-definitions.md | 17 +++--- .../4-contract-definitions.md | 24 ++++----- .../5-catalog.md | 29 ++++------ .../6-contract-negotiation.md | 53 +++++-------------- .../7-transfer-process.md | 34 +++++------- 6 files changed, 78 insertions(+), 118 deletions(-) diff --git a/docs/samples/management-api-v2-walkthrough/2-assets.md b/docs/samples/management-api-v2-walkthrough/2-assets.md index d05bf7c74..8a3c8eabb 100644 --- a/docs/samples/management-api-v2-walkthrough/2-assets.md +++ b/docs/samples/management-api-v2-walkthrough/2-assets.md @@ -5,17 +5,18 @@ ```json { "asset": { - "id": "asset-id", + "id": "", "properties": { - "name": "asset-name", - "description": "asset-description", - "version": "0.0.1", - "contenttype": "application/json" + "name": "", + "description": "", + "version": "", + "contenttype": "" } }, "dataAddress": { - "type": "asset-address-type", - "keyName": "asset-key-name" + "properties": { + "type": "" + } } } ``` @@ -31,21 +32,19 @@ }, "@type": "AssetEntryDto", "asset": { - "@id": "asset-id", + "@id": "", "properties": { - "name": "asset-name", - "description": "asset-description", - "version": "0.0.1", - "contenttype": "application/json" + "name": "", + "description": "", + "version": "", + "contenttype": "" }, "privateProperties": { - "pvt-prop-1": "prt-prov-val-1", - "pvt-prop-2": "prt-prov-val-2" + "private-property": "", } }, "dataAddress": { - "type": "asset-address-type", - "keyName": "asset-key-name" + "type": "" } } ``` @@ -55,7 +54,9 @@ Private properties will not be sent through the dataplane and are only accessibl 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. +> 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 @@ -75,8 +76,8 @@ curl -X POST "${MANAGEMENT_URL}/v2/assets" \ "@id": "asset-id" }, "dataAddress": { - "type": "asset-address-type", - "keyName": "asset-key-name" + "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 index aaa207be3..7acf439ff 100644 --- a/docs/samples/management-api-v2-walkthrough/3-policy-definitions.md +++ b/docs/samples/management-api-v2-walkthrough/3-policy-definitions.md @@ -4,7 +4,7 @@ ```json { - "id": "policy-definition-id", + "id": "", "policy": { "permissions": [ { @@ -14,12 +14,12 @@ "constraints": [ { "leftExpression": { - "value": "BusinessPartnerNumber" + "value": "" }, "rightExpression": { - "value": "BPN" + "value": "" }, - "operator": "eq" + "operator": "" } ] } @@ -33,6 +33,7 @@ ## 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 @@ -42,16 +43,16 @@ Policy model is now pure [ODRL (Open Digital Rights Language)](https://www.w3.or "odrl": "http://www.w3.org/ns/odrl/2/" }, "@type":"PolicyDefinition", - "@id": "policy-definition-id", + "@id": "", "policy": { "odrl:permission": [ { "odrl:action": "USE", "odrl:constraint": [ { - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": "eq", - "odrl:rightOperand": "BPN" + "odrl:leftOperand": "", + "odrl:operator": "", + "odrl:rightOperand": "" }] } ], diff --git a/docs/samples/management-api-v2-walkthrough/4-contract-definitions.md b/docs/samples/management-api-v2-walkthrough/4-contract-definitions.md index d02c34fb8..2b308e39b 100644 --- a/docs/samples/management-api-v2-walkthrough/4-contract-definitions.md +++ b/docs/samples/management-api-v2-walkthrough/4-contract-definitions.md @@ -4,14 +4,14 @@ ```json { - "id": "contract-definition-id", - "accessPolicyId": "policy-id", - "contractPolicyId": "policy-id", + "id": "", + "accessPolicyId": "", + "contractPolicyId": "", "assetsSelector": [ { - "operandLeft": "id", - "operator": "=", - "operandRight": "asset-id" + "operandLeft": "", + "operator": "", + "operandRight": "" } ] } @@ -27,14 +27,14 @@ "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }, "@type": "ContractDefinition", - "@id": "contract-definition-id", - "accessPolicyId": "policy-id", - "contractPolicyId": "policy-id", + "@id": "", + "accessPolicyId": "", + "contractPolicyId": "", "assetsSelector": [ { - "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", - "operator": "=", - "operandRight": "asset-id" + "operandLeft": "", + "operator": "", + "operandRight": "" } ] } diff --git a/docs/samples/management-api-v2-walkthrough/5-catalog.md b/docs/samples/management-api-v2-walkthrough/5-catalog.md index 79448ad6b..e865f9350 100644 --- a/docs/samples/management-api-v2-walkthrough/5-catalog.md +++ b/docs/samples/management-api-v2-walkthrough/5-catalog.md @@ -5,7 +5,7 @@ ```json { "protocol" : "ids-protocol-http", - "providerUrl": "http://provider-control-plane:8282/api/v1/ids", + "providerUrl": "", "querySpec": { "offset": 0, "limit": 100, @@ -27,27 +27,25 @@ ```json { "@context": { - "vocab": "https://w3id.org/edc/v0.0.1/ns/" + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }, "protocol" : "dataspace-protocol-http", - "providerUrl": "http://provider-control-plane:8282/api/v1/dsp", + "providerUrl": "", "querySpec": { "offset": 0, "limit": 100, - "filter": "", - "range": { - "from": 0, - "to": 100 - }, - "sortField": "", - "criterion": "" + "filterExpression": { + "operandLeft": "", + "operator": "", + "operandRight": "" + } } } ``` ## Request -In this case we fetch a provider catalog without using `queryspec`. +In this case we fetch a provider catalog. ```bash curl -X POST "${MANAGEMENT_URL}/v2/catalog/request" \ @@ -61,14 +59,7 @@ curl -X POST "${MANAGEMENT_URL}/v2/catalog/request" \ "providerUrl": "http://provider-control-plane:8282/api/v1/dsp", "querySpec": { "offset": 0, - "limit": 100, - "filter": "", - "range": { - "from": 0, - "to": 100 - }, - "sortField": "", - "criterion": "" + "limit": 100 } }' \ -s -o /dev/null -w 'Response Code: %{http_code}\n' diff --git a/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md b/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md index 8820bc20b..b80eb16f9 100644 --- a/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md +++ b/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md @@ -6,30 +6,13 @@ { "connectorAddress": "provider-dsp-url", "protocol": "dataspace-protocol-http", - "connectorId": "provider-id", - "providerId": "provider-id", + "connectorId": "", + "providerId": "", "offer": { - "offerId": "offer-id", - "assetId": "asset-id", + "offerId": "", + "assetId": "", "policy": { - "permissions": [ - { - "action": { - "type": "USE" - }, - "constraints": [ - { - "leftExpression": { - "value": "BusinessPartnerNumber" - }, - "rightExpression": { - "value": "BPN" - }, - "operator": "EQ" - } - ] - } - ], + "permissions": [], "prohibition": [], "obligation": [] } @@ -50,33 +33,23 @@ "@type": "NegotiationInitiateRequestDto", "connectorAddress": "provider-dsp-url", "protocol": "dataspace-protocol-http", - "connectorId": "provider-id", - "providerId": "provider-id", + "connectorId": "", + "providerId": "", "offer": { - "offerId": "offer-id", - "assetId": "asset-id", + "offerId": "", + "assetId": "", "policy": { "@type": "odrl:Set", - "odrl:permission": { - "odrl:target": "asset-id", - "odrl:action": { - "odrl:type": "USE" - }, - "odrl:constraint": { - "odrl:or": { - "odrl:leftOperand": "BusinessPartnerNumber", - "odrl:operator": "EQ", - "odrl:rightOperand": "BPN" - } - } - }, + "odrl:permission": [], "odrl:prohibition": [], "odrl:obligation": [], - "odrl:target": "asset-id" + "odrl:target": "" } } } ``` +The `offerId` and `policy` must be the `odrl:Set` `@id` and content, respectively, of the one you chose to agree with from the `dcat:dataset` in the `dcat:catalog`. + ## Request diff --git a/docs/samples/management-api-v2-walkthrough/7-transfer-process.md b/docs/samples/management-api-v2-walkthrough/7-transfer-process.md index 2ed86900a..1b7936b03 100644 --- a/docs/samples/management-api-v2-walkthrough/7-transfer-process.md +++ b/docs/samples/management-api-v2-walkthrough/7-transfer-process.md @@ -4,17 +4,17 @@ ```json { - "assetId": "asset-id", - "connectorAddress": "provider-dsp-url", - "contractId": "contract-agreement-id", + "assetId": "", + "connectorAddress": "", + "contractId": "", "dataDestination": { "properties": { - "type": "HttpProxy" + "type": "" } }, "managedResources": false, "privateProperties": { - "receiverHttpEndpoint": "backend-service-endpoint" + "receiverHttpEndpoint": "" }, "protocol": "ids-protocol-http", "transferType": { @@ -34,24 +34,22 @@ "@vocab": "https://w3id.org/edc/v0.0.1/ns/", "odrl": "http://www.w3.org/ns/odrl/2/" }, - "assetId": "asset-id", - "connectorAddress": "provider-dsp-url", - "contractId": "contract-agreement-id", + "assetId": "", + "connectorAddress": "", + "contractId": "", "dataDestination": { - "type": "HttpProxy" + "type": "" }, "managedResources": false, "privateProperties": { - "receiverHttpEndpoint": "backend-service-endpoint" + "receiverHttpEndpoint": "" }, "protocol": "dataspace-protocol-http", - "transferType": { - "contentType": "application/octet-stream", - "isFinite": true - } } ``` +`dataDestination` should correspond to one of the supported types listed in the provider's catalog `dcat:distribution`, and it should include all the necessary properties associated with the chosen type. + ## Request In this case we initiate a transfer process with the provider. @@ -73,13 +71,9 @@ curl -X POST "${MANAGEMENT_URL}/v2/transferprocesses" \ }, "managedResources": false, "privateProperties": { - "receiverHttpEndpoint": "backend-service-endpoint" + "receiverHttpEndpoint": "http://receiver/endpoint" }, - "protocol": "dataspace-protocol-http", - "transferType": { - "contentType": "application/octet-stream", - "isFinite": true - } + "protocol": "dataspace-protocol-http" }' \ -s -o /dev/null -w 'Response Code: %{http_code}\n' ``` From 30010b3604e2b6d4074bcdc20467d0702999c780 Mon Sep 17 00:00:00 2001 From: yurimssilva Date: Mon, 10 Jul 2023 08:58:09 +0100 Subject: [PATCH 6/6] fix: mardownlint reports --- docs/samples/management-api-v2-walkthrough/2-assets.md | 6 +++--- .../management-api-v2-walkthrough/6-contract-negotiation.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/samples/management-api-v2-walkthrough/2-assets.md b/docs/samples/management-api-v2-walkthrough/2-assets.md index 8a3c8eabb..0da7bb928 100644 --- a/docs/samples/management-api-v2-walkthrough/2-assets.md +++ b/docs/samples/management-api-v2-walkthrough/2-assets.md @@ -54,9 +54,9 @@ Private properties will not be sent through the dataplane and are only accessibl 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. +> 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 diff --git a/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md b/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md index b80eb16f9..c1b5db050 100644 --- a/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md +++ b/docs/samples/management-api-v2-walkthrough/6-contract-negotiation.md @@ -48,8 +48,8 @@ } } ``` -The `offerId` and `policy` must be the `odrl:Set` `@id` and content, respectively, of the one you chose to agree with from the `dcat:dataset` in the `dcat:catalog`. +The `offerId` and `policy` must be the `odrl:Set` `@id` and content, respectively, of the one you chose to agree with from the `dcat:dataset` in the `dcat:catalog`. ## Request