diff --git a/docs/samples/edr-api-overview/edr-api-overview.md b/docs/samples/edr-api-overview/edr-api-overview.md index 578cc6ecd..3cfbba516 100644 --- a/docs/samples/edr-api-overview/edr-api-overview.md +++ b/docs/samples/edr-api-overview/edr-api-overview.md @@ -75,6 +75,37 @@ This endpoint will perform the contract negotiation, transfer process and EDR st } ``` +The EDR negotiation returns only the id of the negotiation process that has been started. + +The EDR negotiation rely on two steps, contract negotiation and transfer process, both of which are asynchronous. +In order to plug-in and get notified in every state of the two state machines, callbacks can be configured while starting +the EDR negotiation: + +```json +{ + ... + "callbackAddresses": [ + { + "uri": "http://localhost:8080/hooks", + "events": [ + "transfer.process.started" + ], + "transactional": false + } + ] +} +``` + +In this case we are interested only when the transfer process transition to the `STARTED` state. + +Once the EDR has been negotiated with the provider, the EDR itself will be stored in the configured vault and the metadata +associated to it in the configured datasource for future querying. + +Since `tractusx-edc` v0.5.1 the cached EDRs also come with a state machine that will manage the lifecycle of an EDR +on the consumer side. That means that it will auto-renew itself when the expiration date is approaching by +firing another transfer process request with the same parameters as the original one. Once renewed the old-one +will transition to the state `EXPIRED` and it will be removed from the database and the vault according to the [configuration](../../../core/edr-core/README.md) + ### EDR Management | Fetch cached EDRs This endpoint will retrieve all EDR entries by their `assetId` or `agreementId` references, which are passed as `query parameters`. @@ -89,9 +120,12 @@ This endpoint will retrieve all EDR entries by their `assetId` or `agreementId` [ { "@type": "tx:EndpointDataReferenceEntry", - "edc:agreementId": "contract-agreement-id", - "edc:transferProcessId": "transfer-process-id", - "edc:assetId": "asset-id", + "edc:agreementId": "MQ==:MQ==:NGU2MWRhMzQtNTUwOC00MDU1LThhZjUtYzZhODdlOTUxY2Ux", + "edc:transferProcessId": "3f79d8e0-830b-434b-ada2-d2c4c1271c8f", + "edc:assetId": "1", + "edc:providerId": "BPNL000000000001", + "tx:edrState": "NEGOTIATED", + "tx:expirationDate": 1693928132000, "@context": { "dct": "https://purl.org/dc/terms/", "tx": "https://w3id.org/tractusx/v0.0.1/ns/", @@ -104,6 +138,8 @@ This endpoint will retrieve all EDR entries by their `assetId` or `agreementId` ] ``` +### EDR Management | Fetch single EDR + This endpoint, through the `transfer-process-id` passed as `path variable`, will retrieve the actual EDR. | Path | Method | Query Params | @@ -133,3 +169,85 @@ This endpoint, through the `transfer-process-id` passed as `path variable`, will ``` > Please note that now with the EDR you are able to request the `Asset` data from provider's `data-plane`. + +### EDR Management | Deleting a cached EDR + +This endpoint will delete the EDR entry associated with the `transfer-process-id` and it will remove the EDR itself +from the vault. + +| Path | Method | Query Params | +|-----------------------------------------------|--------|--------------------------| +| `/edrs/{transfer-process-id}` | DELETE | none | + +### EDR Usage | Fetching data + +Once the EDR has been negotiated and stored, the data can be fetched in two ways depending on the use-case: + +- Provider data-plane (EDC way) +- Consumer proxy (tractus-x EDC simplified) + +#### Provider data-plane + +Once the right EDR has been identified using the EDR management API the current asset/agreement/transfer-process that +you want to transfer, we can use the `endpont`, `authCode` and `authKey` to make the request: + +```sh +curl --request GET \ + --url http://provider-data-plane/public-url \ + --header 'Authorization: auth-code' \ + --header 'Content-Type: application/json' +``` + +If the HTTP asset exposed has been configured to proxy also query parameters and path segments they will be forwarded +to the backend from the provider data-plane: + +```sh +curl --request GET \ + --url http://provider-data-plane/public-url/subroute?foo=bar \ + --header 'Authorization: auth-code' \ + --header 'Content-Type: application/json' +``` + +#### Consumer data-plane (proxy) + +The Consumer data-plane proxy is an extension available in `tractusx-edc` that will use the EDR store to simplify +the data request on consumer side. The documentation is available [here](../../../edc-extensions/dataplane-proxy/edc-dataplane-proxy-consumer-api/README.md). + +The only API is: + +| Path | Method | Query Params | +|---------------------------|--------|--------------------------| +| `/aas/request` | POST | none | + +which fetches the data according to the input body. The body should contain the `assetId` plus `providerId` or the `transferProcessId`, +which identifies the EDR to use for fetching data and an `endpointUrl` which is the [provider gateway](../../../edc-extensions/dataplane-proxy/edc-dataplane-proxy-provider-api/README.md) +on which the data is available. + +Example: + +```sh +curl --request POST \ + --url http://localhost:8186/proxy/aas/request \ + --header 'Content-Type: application/json' \ + --header 'X-Api-Key: password' \ + --data '{"assetId": "1","providerId": "BPNL000000000001","endpointUrl": "http://localhost:8080/api/gateway/aas/test"}' +``` + +Alternatively if the `endpointUrl` is not known or the gateway on the provider side is not configured, it can be omitted and the `Edr#endpointUrl` +will be used as base url. In this scenario if needed, users can provide additional properties to the request for composing the final +url: + +- `pathSegments` sub path to append to the base url +- `queryParams` query parameters to add to the url + +Example of an asset with base url `http://localhost:8080/test` + +```sh +curl --request POST \ + --url http://localhost:8186/proxy/aas/request \ + --header 'Content-Type: application/json' \ + --header 'X-Api-Key: password' \ + --data '{"assetId": "1","providerId": "BPNL000000000001","pathSegments": "/sub","queryParams": "foo=bar"}' +``` + +The final url will look like `http://localhost:8080/test/sub?foo=bar`. diff --git a/edc-extensions/dataplane-proxy/edc-dataplane-proxy-consumer-api/README.md b/edc-extensions/dataplane-proxy/edc-dataplane-proxy-consumer-api/README.md index ec590c1a2..45e337d9d 100644 --- a/edc-extensions/dataplane-proxy/edc-dataplane-proxy-consumer-api/README.md +++ b/edc-extensions/dataplane-proxy/edc-dataplane-proxy-consumer-api/README.md @@ -36,7 +36,7 @@ Example with base url `http://localhost:8080/test` The final url will look like `http://localhost:8080/test/sub?foo=bar` composed by the DataPlane manager with the Http request flow, -> Note: the endpoint is not protected with configured `AuthenticationService`, which most likely will be the token based (auth key) one. +> Note: the endpoint is protected with configured `AuthenticationService`. ## Configuration