diff --git a/docs/usage/bruno/README.md b/docs/usage/bruno/README.md new file mode 100644 index 0000000000..f4293f7a64 --- /dev/null +++ b/docs/usage/bruno/README.md @@ -0,0 +1,39 @@ +# API Requests for Data Exchange + +This document provides information about API requests for the Data Exchange. + +## Roles +- Data Consumer - Alice +- Data Provider - Bob + +## Bruno + +The Bruno collection contains all the data exchange flow between Alice and Bob. + +### Setting Up Bruno + +[Download](https://www.usebruno.com/downloads) Bruno client suitable for your operating system + +### Import Collection + +- Open the following [Collection](./constructx-edc) in Bruno using the dots at the left top corner. + + +![collection-import](media/open-collection.png) + +### Import Envrionments + +Once the collection is imported, import the [Environment](./environments.json) at the top right corner, + +![environment-import](./media/import-environment.png) + + +The collection is adopted from [Eclipse-TractusX Umbrella - API Testing](https://github.com/eclipse-tractusx/tractus-x-umbrella/tree/release-25.09/docs/api) + +## NOTICE + +This work is licensed under the [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0). + +* SPDX-License-Identifier: Apache-2.0 +* SPDX-FileCopyrightText: 2024 Contributors to the Eclipse Foundation +* Source URL: \ No newline at end of file diff --git a/docs/usage/bruno/constructx-edc/01-Provide_Data/01-Create The Data.bru b/docs/usage/bruno/constructx-edc/01-Provide_Data/01-Create The Data.bru new file mode 100644 index 0000000000..4acd6bdab4 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/01-Provide_Data/01-Create The Data.bru @@ -0,0 +1,36 @@ +meta { + name: 01-Create The Data + type: http + seq: 1 +} + +post { + url: {{Bob_Data_Server}}/urn:uuid:b77c6d51-cd1f-4c9d-b5d4-091b22dd306b + body: json + auth: inherit +} + +headers { + Content-Type: application/json +} + +body:json { + { + "parentParts": [ + { + "validityPeriod": { + "validFrom": "2023-03-21T08:47:14.438+01:00", + "validTo": "2024-08-02T09:00:00.000+01:00" + }, + "parentCatenaXId": "urn:uuid:0733946c-59c6-41ae-9570-cb43a6e4c79e", + "quantity": { + "quantityNumber": 2.5, + "measurementUnit": "unit:litre" + }, + "createdOn": "2022-02-03T14:48:54.709Z", + "lastModifiedOn": "2022-02-03T14:48:54.709Z" + } + ], + "catenaXId": "urn:uuid:2c57b0e9-a653-411d-bdcd-64787e9fd3a7" + } +} diff --git a/docs/usage/bruno/constructx-edc/01-Provide_Data/02-Verify Data is Created.bru b/docs/usage/bruno/constructx-edc/01-Provide_Data/02-Verify Data is Created.bru new file mode 100644 index 0000000000..7cddb557a4 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/01-Provide_Data/02-Verify Data is Created.bru @@ -0,0 +1,11 @@ +meta { + name: 02-Verify Data is Created + type: http + seq: 2 +} + +get { + url: {{Bob_Data_Server}}/urn:uuid:b77c6d51-cd1f-4c9d-b5d4-091b22dd306b + body: none + auth: inherit +} diff --git a/docs/usage/bruno/constructx-edc/01-Provide_Data/03-Create The Asset.bru b/docs/usage/bruno/constructx-edc/01-Provide_Data/03-Create The Asset.bru new file mode 100644 index 0000000000..f1f6692f64 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/01-Provide_Data/03-Create The Asset.bru @@ -0,0 +1,43 @@ +meta { + name: 03-Create The Asset + type: http + seq: 3 +} + +post { + url: {{Bob}}/assets + body: json + auth: apikey +} + +auth:apikey { + key: X-Api-Key + value: {{Bob_Api_Key}} + placement: header +} + +body:json { + { + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "tx-auth": "https://w3id.org/tractusx/auth/", + "cx-policy": "https://w3id.org/catenax/policy/", + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@id": "{{ASSET_ID}}", + "properties": { + "description": "Product EDC Demo Asset" + }, + "dataAddress": { + "@type": "DataAddress", + "type": "HttpData", + "proxyPath": "true", + "proxyMethod": "true", + "proxyQueryParams": "true", + "proxyBody": "true", + "baseUrl": "http://dataprovider-submodelserver.tx.test" + } + } +} diff --git a/docs/usage/bruno/constructx-edc/01-Provide_Data/04-Validate The Asset.bru b/docs/usage/bruno/constructx-edc/01-Provide_Data/04-Validate The Asset.bru new file mode 100644 index 0000000000..b9db54de9d --- /dev/null +++ b/docs/usage/bruno/constructx-edc/01-Provide_Data/04-Validate The Asset.bru @@ -0,0 +1,17 @@ +meta { + name: 04-Validate The Asset + type: http + seq: 4 +} + +get { + url: {{Bob}}/assets/{{ASSET_ID}} + body: none + auth: apikey +} + +auth:apikey { + key: X-Api-Key + value: {{Bob_Api_Key}} + placement: header +} diff --git a/docs/usage/bruno/constructx-edc/01-Provide_Data/05-Create The Policy.bru b/docs/usage/bruno/constructx-edc/01-Provide_Data/05-Create The Policy.bru new file mode 100644 index 0000000000..a805963371 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/01-Provide_Data/05-Create The Policy.bru @@ -0,0 +1,60 @@ +meta { + name: 05-Create The Policy + type: http + seq: 5 +} + +post { + url: {{Bob}}/policydefinitions + body: json + auth: apikey +} + +auth:apikey { + key: X-Api-Key + value: {{Bob_Api_Key}} + placement: header +} + +body:json { + { + "@context": [ + "https://w3id.org/catenax/2025/9/policy/odrl.jsonld", + "https://w3id.org/catenax/2025/9/policy/context.jsonld", + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + } + ], + "@id": "{{ACCESS_POLICY_ID}}", + "@type": "PolicyDefinition", + "policy": { + "@type": "Set", + "permission": [ + { + "action": "access", + "constraint": [ + { + "and": [ + { + "leftOperand": "Membership", + "operator": "eq", + "rightOperand": "active" + }, + { + "leftOperand": "FrameworkAgreement", + "operator": "eq", + "rightOperand": "DataExchangeGovernance:1.0" + }, + { + "leftOperand": "BusinessPartnerNumber", + "operator": "isAnyOf", + "rightOperand": ["{{Alice_BPN}}"] + } + ] + } + ] + } + ] + } + } +} diff --git a/docs/usage/bruno/constructx-edc/01-Provide_Data/05_2-Create The Policy.bru b/docs/usage/bruno/constructx-edc/01-Provide_Data/05_2-Create The Policy.bru new file mode 100644 index 0000000000..32213e2c3e --- /dev/null +++ b/docs/usage/bruno/constructx-edc/01-Provide_Data/05_2-Create The Policy.bru @@ -0,0 +1,63 @@ +meta { + name: 05_2-Create The Policy + type: http + seq: 6 +} + +post { + url: {{Bob}}/policydefinitions + body: json + auth: apikey +} + +auth:apikey { + key: X-Api-Key + value: {{Bob_Api_Key}} + placement: header +} + +body:json { + { + "@context": [ + "https://w3id.org/catenax/2025/9/policy/odrl.jsonld", + "https://w3id.org/catenax/2025/9/policy/context.jsonld", + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + }, + {} + ], + "@type": "PolicyDefinition", + "@id": "{{USAGE_POLICY_ID}}", + "policy": { + "@type": "Set", + "permission": [ + { + "action": "use", + "constraint": { + "and": [ + { + "leftOperand": "Membership", + "operator": "eq", + "rightOperand": "active" + }, + { + "leftOperand": "FrameworkAgreement", + "operator": "eq", + "rightOperand": "DataExchangeGovernance:1.0" + }, + { + "leftOperand": "UsagePurpose", + "operator": "isAnyOf", + "rightOperand": [ + "cx.core.industrycore:1" + ] + } + ] + } + } + ], + "prohibition": [], + "obligation": [] + } + } +} diff --git a/docs/usage/bruno/constructx-edc/01-Provide_Data/06-Validate The Policy.bru b/docs/usage/bruno/constructx-edc/01-Provide_Data/06-Validate The Policy.bru new file mode 100644 index 0000000000..65ec9814fb --- /dev/null +++ b/docs/usage/bruno/constructx-edc/01-Provide_Data/06-Validate The Policy.bru @@ -0,0 +1,17 @@ +meta { + name: 06-Validate The Policy + type: http + seq: 7 +} + +get { + url: {{Bob}}/policydefinitions/{{ACCESS_POLICY_ID}} + body: none + auth: apikey +} + +auth:apikey { + key: X-Api-Key + value: {{Bob_Api_Key}} + placement: header +} diff --git a/docs/usage/bruno/constructx-edc/01-Provide_Data/07-Create The Contract Definition.bru b/docs/usage/bruno/constructx-edc/01-Provide_Data/07-Create The Contract Definition.bru new file mode 100644 index 0000000000..87f9dbc421 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/01-Provide_Data/07-Create The Contract Definition.bru @@ -0,0 +1,37 @@ +meta { + name: 07-Create The Contract Definition + type: http + seq: 8 +} + +post { + url: {{Bob}}/contractdefinitions + body: json + auth: apikey +} + +auth:apikey { + key: X-Api-Key + value: {{Bob_Api_Key}} + placement: header +} + +body:json { + { + "@context": { + "edc": "https://w3id.org/edc/v0.0.1/ns/" + }, + "@id": "{{CONTRACT_ID}}", + "@type": "ContractDefinition", + "accessPolicyId": "{{ACCESS_POLICY_ID}}", + "contractPolicyId": "{{USAGE_POLICY_ID}}", + "assetsSelector": [ + { + "@type": "CriterionDto", + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "{{ASSET_ID}}" + } + ] + } +} diff --git a/docs/usage/bruno/constructx-edc/01-Provide_Data/08-Validate The Contract Definition.bru b/docs/usage/bruno/constructx-edc/01-Provide_Data/08-Validate The Contract Definition.bru new file mode 100644 index 0000000000..2bdb4ff9ed --- /dev/null +++ b/docs/usage/bruno/constructx-edc/01-Provide_Data/08-Validate The Contract Definition.bru @@ -0,0 +1,17 @@ +meta { + name: 08-Validate The Contract Definition + type: http + seq: 9 +} + +get { + url: {{Bob}}/contractdefinitions/{{CONTRACT_ID}} + body: none + auth: apikey +} + +auth:apikey { + key: X-Api-Key + value: {{Bob_Api_Key}} + placement: header +} diff --git a/docs/usage/bruno/constructx-edc/01-Provide_Data/folder.bru b/docs/usage/bruno/constructx-edc/01-Provide_Data/folder.bru new file mode 100644 index 0000000000..9944833388 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/01-Provide_Data/folder.bru @@ -0,0 +1,4 @@ +meta { + name: 01-Provide_Data + seq: 2 +} diff --git a/docs/usage/bruno/constructx-edc/02-Consume_Data/01-Request Contract Offers.bru b/docs/usage/bruno/constructx-edc/02-Consume_Data/01-Request Contract Offers.bru new file mode 100644 index 0000000000..9439179dc8 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/02-Consume_Data/01-Request Contract Offers.bru @@ -0,0 +1,46 @@ +meta { + name: 01-Request Contract Offers + type: http + seq: 1 +} + +post { + url: {{Alice}}/management/v3/catalog/request + body: json + auth: apikey +} + +auth:apikey { + key: X-Api-Key + value: {{Alice_Api_Key}} + placement: header +} + +body:json { + { + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "odrl": "http://www.w3.org/ns/odrl/2/", + "dct": "http://purl.org/dc/terms/" + }, + "@type": "CatalogRequest", + "counterPartyId": "{{Bob_DID}}", + "counterPartyAddress": "{{Bob_DSP}}/2025-1", + "protocol": "dataspace-protocol-http:2025-1", + "querySpec": { + "filterExpression": [ + { + "operandLeft": "https://w3id.org/edc/v0.0.1/ns/id", + "operator": "=", + "operandRight": "{{ASSET_ID}}" + } + ] + } + } +} + +tests { + const response = res.getBody(); + const offerId = response.dataset[0].hasPolicy[0]["@id"]; + bru.setVar("OFFER_ID", offerId); +} diff --git a/docs/usage/bruno/constructx-edc/02-Consume_Data/02-EDR Request.bru b/docs/usage/bruno/constructx-edc/02-Consume_Data/02-EDR Request.bru new file mode 100644 index 0000000000..3143ffed69 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/02-Consume_Data/02-EDR Request.bru @@ -0,0 +1,76 @@ +meta { + name: 02-EDR Request + type: http + seq: 2 +} + +post { + url: {{Alice}}/edrs + body: json + auth: apikey +} + +headers { + Content-Type: application/json +} + +auth:apikey { + key: X-Api-Key + value: {{Alice_Api_Key}} + placement: header +} + +body:json { + { + "@context": [ + "http://www.w3.org/ns/odrl.jsonld", + "https://w3id.org/catenax/2025/9/policy/context.jsonld", + { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/" + } + ], + "@type": "ContractRequest", + "counterPartyAddress": "{{Bob_DSP}}/2025-1", + "protocol": "dataspace-protocol-http:2025-1", + "policy": { + "@id": "{{OFFER_ID}}", + "@type": "Offer", + "assigner": "{{Bob_DID}}", + "target": "{{ASSET_ID}}", + "permission": [ + { + "action": "use", + "constraint": [ + { + "and": [ + { + "leftOperand": "Membership", + "operator": "eq", + "rightOperand": "active" + }, + { + "leftOperand": "FrameworkAgreement", + "operator": "eq", + "rightOperand": "DataExchangeGovernance:1.0" + }, + { + "leftOperand": "UsagePurpose", + "operator": "isAnyOf", + "rightOperand": "cx.core.industrycore:1" + } + ] + } + ] + } + ], + "prohibition": [], + "obligation": [] + }, + "callbackAddresses": [] + } +} + +tests { + const contractnegotiationId = res.body["@id"]; + bru.setVar("CONTRACT_NEGOTIATION_ID", contractnegotiationId); +} diff --git a/docs/usage/bruno/constructx-edc/02-Consume_Data/03-Query Cached EDRs Response.bru b/docs/usage/bruno/constructx-edc/02-Consume_Data/03-Query Cached EDRs Response.bru new file mode 100644 index 0000000000..3da4a8a219 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/02-Consume_Data/03-Query Cached EDRs Response.bru @@ -0,0 +1,40 @@ +meta { + name: 03-Query Cached EDRs Response + type: http + seq: 3 +} + +post { + url: {{Alice}}/edrs/request + body: json + auth: apikey +} + +headers { + Content-Type: application/json +} + +auth:apikey { + key: X-Api-Key + value: {{Alice_Api_Key}} + placement: header +} + +body:json { + { + "@context": { "@vocab": "https://w3id.org/edc/v0.0.1/ns/" }, + "@type": "QuerySpec", + "filterExpression": [ + { + "operandLeft": "contractNegotiationId", + "operator": "=", + "operandRight": "{{CONTRACT_NEGOTIATION_ID}}" + } + ] + } +} + +tests { + const transferProcessId = res.body[0].transferProcessId; + bru.setVar("TRANSFER_PROCESS_ID", transferProcessId); +} diff --git a/docs/usage/bruno/constructx-edc/02-Consume_Data/04-Get Authorization Details.bru b/docs/usage/bruno/constructx-edc/02-Consume_Data/04-Get Authorization Details.bru new file mode 100644 index 0000000000..923e9045ee --- /dev/null +++ b/docs/usage/bruno/constructx-edc/02-Consume_Data/04-Get Authorization Details.bru @@ -0,0 +1,29 @@ +meta { + name: 04-Get Authorization Details + type: http + seq: 4 +} + +get { + url: {{Alice}}/edrs/{{TRANSFER_PROCESS_ID}}/dataaddress?auto_refresh=true + body: none + auth: apikey +} + +params:query { + auto_refresh: true +} + +auth:apikey { + key: X-Api-Key + value: {{Alice_Api_Key}} + placement: header +} + +tests { + const endpoint = res.body.endpoint; + const authorization = res.body.authorization; + + bru.setVar("ENDPOINT", endpoint); + bru.setVar("TOKEN", authorization); +} diff --git a/docs/usage/bruno/constructx-edc/02-Consume_Data/05-Fetch Data.bru b/docs/usage/bruno/constructx-edc/02-Consume_Data/05-Fetch Data.bru new file mode 100644 index 0000000000..5f1e5321e8 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/02-Consume_Data/05-Fetch Data.bru @@ -0,0 +1,15 @@ +meta { + name: 05-Fetch Data + type: http + seq: 5 +} + +get { + url: {{ENDPOINT}}/urn:uuid:b77c6d51-cd1f-4c9d-b5d4-091b22dd306b + body: none + auth: none +} + +headers { + Authorization: {{TOKEN}} +} diff --git a/docs/usage/bruno/constructx-edc/02-Consume_Data/folder.bru b/docs/usage/bruno/constructx-edc/02-Consume_Data/folder.bru new file mode 100644 index 0000000000..d45ec56cdb --- /dev/null +++ b/docs/usage/bruno/constructx-edc/02-Consume_Data/folder.bru @@ -0,0 +1,4 @@ +meta { + name: 02-Consume_Data + seq: 3 +} diff --git a/docs/usage/bruno/constructx-edc/bruno.json b/docs/usage/bruno/constructx-edc/bruno.json new file mode 100644 index 0000000000..dd59301fca --- /dev/null +++ b/docs/usage/bruno/constructx-edc/bruno.json @@ -0,0 +1,5 @@ +{ + "version": "1", + "name": "constructx-edc", + "type": "collection" +} \ No newline at end of file diff --git a/docs/usage/bruno/constructx-edc/collection.bru b/docs/usage/bruno/constructx-edc/collection.bru new file mode 100644 index 0000000000..f822aa951d --- /dev/null +++ b/docs/usage/bruno/constructx-edc/collection.bru @@ -0,0 +1,16 @@ +vars:pre-request { + Bob: http://dataprovider-controlplane.tx.test/management/v3 + Bob_DSP: http://dataprovider-controlplane.tx.test/api/v1/dsp + Alice: http://dataconsumer-1-controlplane.tx.test/management/v3 + Bob_BPN: BPNL00000003AYRE + Alice_BPN: BPNL00000003AZQP + Bob_Data_Server: http://dataprovider-submodelserver.tx.test + ASSET_ID: 201 + ACCESS_POLICY_ID: 207 + CONTRACT_ID: 207 + Alice_Api_Key: TEST1 + Bob_Api_Key: TEST2 + Alice_DID: did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP + Bob_DID: did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AYRE + USAGE_POLICY_ID: 208 +} \ No newline at end of file diff --git a/docs/usage/bruno/constructx-edc/environments/CX-EDC Local.bru b/docs/usage/bruno/constructx-edc/environments/CX-EDC Local.bru new file mode 100644 index 0000000000..929b69b605 --- /dev/null +++ b/docs/usage/bruno/constructx-edc/environments/CX-EDC Local.bru @@ -0,0 +1,13 @@ +vars { + Bob: http://dataprovider-controlplane.tx.test/management/v3 + Bob_DSP: http://dataprovider-controlplane.tx.test/api/v1/dsp + Alice: http://dataconsumer-1-controlplane.tx.test/management/v3 + Bob_BPN: BPNL00000003AYRE + Bob_DID: did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AYRE + Alice_BPN: BPNL00000003AZQP + Alice_DID: did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP + Bob_Data_Server: http://dataprovider-submodelserver.tx.test + ASSET_ID: 200 + POLICY_ID: 200 + CONTRACT_ID: 200 +} diff --git a/docs/usage/bruno/environments.json b/docs/usage/bruno/environments.json new file mode 100644 index 0000000000..039e02f534 --- /dev/null +++ b/docs/usage/bruno/environments.json @@ -0,0 +1,73 @@ +{ + "id": "edc-env", + "name": "CX-EDC Local", + "values": [ + { + "key": "Bob", + "value": "http://dataprovider-controlplane.tx.test/management/v3", + "type": "default", + "enabled": true + }, + { + "key": "Bob_DSP", + "value": "http://dataprovider-controlplane.tx.test/api/v1/dsp", + "type": "default", + "enabled": true + }, + { + "key": "Alice", + "value": "http://dataconsumer-1-controlplane.tx.test/management/v3", + "type": "default", + "enabled": true + }, + { + "key": "Bob_BPN", + "value": "BPNL00000003AYRE", + "type": "default", + "enabled": true + }, + { + "key": "Bob_DID", + "value": "did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AYRE", + "type": "default", + "enabled": true + }, + { + "key": "Alice_BPN", + "value": "BPNL00000003AZQP", + "type": "default", + "enabled": true + }, + { + "key": "Alice_DID", + "value": "did:web:ssi-dim-wallet-stub.tx.test:BPNL00000003AZQP", + "type": "default", + "enabled": true + }, + { + "key": "Bob_Data_Server", + "value": "http://dataprovider-submodelserver.tx.test", + "type": "default", + "enabled": true + }, + { + "key": "ASSET_ID", + "value": "200", + "type": "default", + "enabled": true + }, + { + "key": "POLICY_ID", + "value": "200", + "type": "default", + "enabled": true + }, + { + "key": "CONTRACT_ID", + "value": "200", + "type": "default", + "enabled": true + } + ], + "_postman_variable_scope": "environment" +} diff --git a/docs/usage/bruno/media/import-environment.png b/docs/usage/bruno/media/import-environment.png new file mode 100644 index 0000000000..e08016dcea Binary files /dev/null and b/docs/usage/bruno/media/import-environment.png differ diff --git a/docs/usage/bruno/media/open-collection.png b/docs/usage/bruno/media/open-collection.png new file mode 100644 index 0000000000..fb70fa39bc Binary files /dev/null and b/docs/usage/bruno/media/open-collection.png differ